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1.1 Overview 


This manual describes the Dos, Kbd, Mou, and Vio system functions of 
Microsoft® Operating System/2 (MS@ OS/2). These functions, also called the 
base system functions, let MS OS/2 programs use the operating system to 

carry out tasks such as reading from and writing to disk files; allocating memory; 
starting other programs; and using the keyboard, mouse, and video screen. 


MS OS/2 system functions are designed to be used in C, Pascal, and other high- 
level-language programs, as well as in assembly-language programs. In MS OS/2, 
all programs request operating-system services by calling system functions. 


This chapter, “Introduction,” shows how to use this manual, provides a brief 
description of MS OS/2 calling conventions, illustrates function calls in various 
languages, and outlines MS OS/2 naming conventions. 


Chapter 2, “Functions Directory,” is an alphabetical listing of MS OS/2 base 
system functions. This chapter defines each function’s purpose, gives its syntax, 
describes the function parameters, and gives possible return values. Many func- 
tions also show simple program examples that illustrate how the function is used 
to carry out simple tasks. 


Chapter 3, “Input-and-Output Control Functions,” lists the input-and-output 
control (IOCtl) functions used to control input and output devices such as serial 
ports, the keyboard, and the mouse. 


Chapter 4, “Types, Macros, Structures,” describes the types, macros, and struc- 
tures used by MS OS/2 base system functions. 


Chapter 5, “File Formats,” describes the format of files and other large data 
structures used by MS OS/2 base system functions. These formats include key- 
board translation tables and video I/O fonts. 


Appendix A, “Error Values,” lists error codes and their corresponding values. 


Appendix B, “ANSI Escape Sequences,” lists the escape sequences used by 
MS OS/2. 


Appendix C, “Country and Code-Page Information,” lists information contained 
in the country and code-page files used by MS OS/2 system functions. This 
includes code-page tables, code-page identifiers, and country-specific informa- 
tion. 


This manual is intended to fully describe MS OS/2 base system functions and 
the structures and file formats used with these functions. It does not show how 
to use these. functions to carry out specific tasks. For more information on this 
topic, see the Microsoft Operating System/2 Programmer’s Reference, Volume 1. 
Also, this manual does not describe MS OS/2 Presentation Manager functions. 
Presentation Manager functions let programs use the window-management and 
graphics features of MS OS/2. For more information on MS OS/2 Presentation 
Manager functions, see the Microsoft Operating System/2 Programmer’s Refer- 
ence, Volume 2. 
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4.2 How to Use This Manual 


This manual provides detailed information about each MS OS/2 base system 
function, macro, and structure. Each description has the following format: 


Figure 1.1 
Sample Reference Page 


@ @ DosBeep 
USHORT DosBeep( usFrequency, usDuration) 
(2) USHORT usFrequency; /» frequency in hertz +/ 
USHORT usDuration; /« duration in milliseconds +/ 


© The DosBeep function generates sound from the speaker. 
6 The DosBeep function is a family API function. 


‘@ Parameters usFrequency Specifies the frequency of the sound in hertz (cycles-per- 
second). This parameter can be any value from 0x0025 through Ox7FFF. 


usDuration Specifies the length of the sound in milliseconds. 
@ Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_ FREQUENCY 


- @ Example This example calls the DosBeep function and produces audible tones: 


SHORT i; 

for (i = O; i < 10; i++) £ 
DosBeep (600, 175); 
DosBeep (1200, 175); 


© See Also WinAlarm 


These are the elements shown: 


1 The function, macro, or structure name. 


2 The function, macro, or structure syntax. The syntax specifies the number of 
parameters (or fields) and gives the type of each. It also gives the order (from 
left to right) that parameters must be pushed on the stack. Comments to the 
right briefly describe the purpose of the parameter. 


3 A description of the function, macro, or structure, including its purpose and 
details of operation. 


4 Any special consideration for the function, including whether a function can be 
used in family API programs. 


5 A full description of each parameter (or field), including permitted values and 
related structures. 


6 A description of the function return value, including possible error values. 


ba | 


An example showing how the function can be used to accomplish a simple task. 
8 A list of related functions and structures. . 
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1.2.1 C Format 


In this manual, the syntax for MS OS/2 functions is given in C-language format. 
In your C-language sources, the function name must be spelled exactly as given 
in the syntax, and the parameters must be used in the order given in the syntax. 
This syntax also applies to Pascal program sources. 


The following example shows how to call the DosBeep function in a C-language 
program: 


/* play a note for 1 second */ 


DosBeep (660, /* 660 cycles~per-second */ 
1000) ; /* play for 1000 milliseconds */ 


1.2.2 MS OS/2 Include Files 


This manual uses many types, structures, and constants that are not part of stan- 
dard C language. These items, designed for MS OS/2, are defined in the MS 
OS/2 C-language include files provided with the Microsoft OS/2 Presentation 
Manager Softset and the Microsoft OS/2 Presentation Manager Toolkit. 


In C-language programs, the #include directive specifying os2.h, the MS OS/2 
C-language include file, can be placed at the beginning of the source file to 
include the definitions for the special types, structures, and constants. Although 
there are many MS OS/2 include files, the os2.h file contains the additional 
#include directives needed to process the basic MS OS/2 definitions. 


To speed up processing of the MS OS/2 C-language include files, many defini- 
tions are processed only if the C-language program explicitly defines a corre- 
sponding include constant. An include constant is simply a constant name, with 
the prefix INCL_, that controls a portion of the include files. If a constant is 
defined using the #define directive, the corresponding MS OS/2 definitions are 
processed. For a list of the include constants and a description of the MS OS/2 
system functions they enable, see the Microsoft Operating System/2 Programmer’s 
Reference, Volume 1. 


1.2.3 MS OS/2 Calling Conventions 


You must know MS OS/2 calling conventions to use MS OS/2 functions in other 
high-level languages or in assembly language. MS OS/2 functions use the Pascal 
(sometimes called the PLM) calling convention for passing parameters, and they 
apply some additional rules to support dynamic-link libraries. The following 
rules apply: 


@ You must push the parameters on the stack. In this manual, each function 
description lists the parameters in the order they must be pushed. The left 
parameter must be pushed first, the right parameter last. If a parameter 
specifies an address, the address must be a far address; that is, it must have 
the form selector:offset. The selector must be pushed first, then the offset. 


™@ The function automatically removes the parameters from the stack as it 
returns. This means the function must have a fixed number of parameters. — 
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@ You must use an intersegment call instruction to call the function. This is 
required for all dynamic-link-library functions. 


@ The function returns a value, possibly an error value, in either the ax register 
or the dx:ax register pair. Only the di and si register values are guaranteed to 
be preserved by the function. MS OS/2 base system functions may preserve 
other registers as well, but they do not preserve the flags register. The con- 
tents of the flags register are undefined; specifically, the direction flag in the 
register may be changed. However, if the direction flag was zero before the 
function was called, it will be zero after the function returns. 


The following example shows how MS OS/2 calling conventions apply to the 
DosOpen function in an assembly-language program: 


EXTRN DOSOPEN:FAR 
db 


name "abo", O 

hFile dw re) 

usAction dw @) 

push ds ; filename to open 

push offset name 

push ds ; address of file handle 

push offset hFile 

push ds ; address to store action taken 
push oe usAction 

push ; size of new file O0O100H 

push 166 

push ce) ; file's attribute 

push 0010H _ 3 Create file if it does not exist 
push 0041H . ; open file for writing, share with all 
push ° ; reserved 

push ° 

call DOSOPEN 


The following example shows how to call the same DosOpen function in a C- 
language program. In C, the DosOpen function name, parameter types, and con- 
stant names are defined in 0s2.h, the MS OS/2 C-language include file. 


# include <os2.h> 


HFILE hfile; 
USHORT usAction; 


DosOpen ("abc", /* filename to open * 
&hfile, /* address of file handle */ 
&usAction, 7* address to store action taken */ 
100L, /* size of new file * 
FILE.NORMAL, /* file's attribute */ 
FILE_CREATE, /* create file if it does not exist */ 
OPEN_SHARE_DENYNONE | /* share with all -& 
OPEN_ACCESS_WRITEONLY, /* open for writing &/ 
OL) ; /* reserved * 


1.2.4 Bit Masks in Function Parameters 


Many MS OS/2 system functions accept or return bit masks as part of their 
operation. A bit mask is a collection of two or more bit fields within a single 
; byte, or a short or long value. Bit masks provide a way to pack many Boolean 
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flags (flags whose values represent on/off or true/false values) into a single 
parameter or structure field. In assembly-language programming, it is easy to 
individually set, clear, or test the bits in a bit mask by using instructions that 
modify or examine bits within a byte or a word. In C-language programming, 
however, the programmer does not have direct access to these instructions, so 
the bitwise AND and OR operators typically are used to examine and modify 
the bit masks. 


Since this manual presents the syntax of MS OS/2 system functions in C- 
language syntax, it also defines bit masks in a way that is easiest to work with 
using the C language: as a set of constant values. When a function parameter 

is a bit mask, this manual provides a list of constants (named or numeric) 

that represent the correct values used to set, clear, or examine each field 

in the bit mask. For example, the fbType field of the VIOMODEINFO struc- 
ture in the VioSetMode function specifies three values: VGMT_OTHER, 
VGMT_GRAPHICS, and VGMT_DISABLEBURST. These represent the “set” 
values of the first three fields in the bit mask. Typically, the description associ- 
ated with the value explains the result of the function if the given value is used; 
that is, when the corresponding bit is set. Generally, the opposite result is 
assumed when the value is not used. For example, using VGMT_GRAPHICS in 
the fbType field enables graphics mode; not using it disables graphics mode. 


1.2.5 Scietaree 


Many MS OS/2 system functions use structures as input and output parameters. 
This manual defines all structures and their fields using C-language syntax. In 
most cases, the structure definition presented is copied directly from the C- 
language include files provided with the Microsoft C Optimizing Compiler. Occa- 
sionally, an MS OS/2 function may have a structure that has no corresponding 
include-file definition. In such cases, this manual gives an incomplete form of 
the C-language structure definition to indicate that the structure is not already 
defined in an include file. 


1.3 Naming Conventions 


In this manual, all parameter, variable, structure, field, and constant names con- 
form to MS OS/2 naming conventions. MS OS/2 naming conventions are rules 
that define how to create names that indicate both the purpose and data type of 
an item used with MS OS/2 system functions. These naming conventions are 
used in this manual to help you readily identify the purpose and type of the func- 
tion parameters and structure fields. These conventions are also used in most 
MS OS/2 sample program sources to make the sources more readable and infor- 
mative. 
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1.3.1 Parameter and Field Names 


With MS OS/2 naming conventions, all parameter and field names consist of up 
to three elements: a prefix, a base type, and a qualifier. A name always consists 
of at least a base type. or a qualifier. In most cases, the name also includes a 
prefix. 


The base type, always written in lowercase letters, identifies the data type of the 
item. The prefix, also written in lowercase letters, specifies additional informa- 
tion about the item, such as whether it is a pointer, an array, or a count of 
bytes. The qualifier, a short word or phrase written with the first letter of each 
word uppercase, specifies the purpose of the item. 


There are several standard prefixes and base types. These are used for the data 
types most frequently used with MS OS/2. 


1.3.1.1 Prefixes 
The following is a list of standard prefixes used in MS OS/2 naming conventions: 


Prefix Description 

Pp Pointer. This prefix identifies a far, or 32-bit, pointer to a 
given item. For example, pch is a far pointer to a character. 

np Near pointer. This prefix identifies a near, or 16-bit, pointer 
to a given item. For example, npch is a near pointer to a 
character. 

a Array. This prefix identifies an array of two or more items 
of a given type. For example, ach is an array of characters. 

i Index. This prefix identifies an index into an array. For 
example, ich is an index to one character in an array of 
characters. 

c Count. This prefix identifies a count of items. It is usually 


combined with the base type of the items being counted 
instead of the base type of the actual parameter. For exam- 
ple, cch is a count of characters even though it may be 
declared with the type USHORT. 


h Handle. This prefix is used for values that uniquely identify 
an object but that cannot be used to access the object 
directly. For example, file is a handle of a file. 


off Offset. This prefix is used for values that represent offsets 
from the beginning of a buffer or a structure. For example, 
off is the offset from the beginning of the given segment to 
the specified byte. 


id Identifier. This prefix is used for values that identify an 
object. For example, idSession is a session identifier. 
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1.3.1.2 Base Types 


ventions: 


The following is a list of standard base types used in MS OS/2 naming con- 


Base type 


f 


fs 


sel 


Type/Description 


BOOL. A 16-bit flag or Boolean value. The qualifier should 
describe the condition associated with the flag when it is 
TRUE. For example, fSuccess is TRUE if successful, 
FALSE if not; fError is TRUE if an error occurs and 
FALSE if no error occurs. For objects of type BOOL, a 
zero value implies FALSE; a nonzero value implies TRUE. 


CHAR. An 8-bit signed value. 

SHORT. A 16-bit signed value. 

LONG. A 32-bit signed value. 

UCHAR. An 8-bit unsigned value. 

USHORT. A 16-bit unsigned value. 

ULONG. A 32-bit unsigned value. 

BYTE. An 8 bit unsigned value. Same as uch. 


CHAR[ }. Array of characters, terminated with a null char- 
acter (the last byte is set to zero). 


UCHAR. Array of flags in a byte. This base type is used 
when more than one flag is packed in an 8-bit value. Values 
for such an array are typically created by using the logical 
OR operator to combine two or more values. 


USHORT. Array of flags in a short (16-bit unsigned value). 
This base type is used when more than one flag is packed in 
a 16-bit value. Values for such an array are typically created 
by using the logical OR operator to combine two or more 
values. 


ULONG. Array of flags in a long (32-bit unsigned value). 
This base type is used when more than one flag is packed in 
a 32-bit value. Values for such an array are typically created 
by using the logical OR operator to combine two or more 
values. 


SEL. A 16-bit value used to hold a segment selector. 
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The base type for a structure is usually derived from the structure name. An 
MS OS/2 structure name, always written in uppercase letters, is a word or 
phrase that describes the size, purpose, and/or intended content associated 
with the type. The base type is typically an abbreviation of the structure name. 
The following list gives the base types for the structures described in this 


manual: 


ctryc 
ctryi 
date 
dcbinf 
trckl 
bspblk 
fdate 
Scrgrp 
findbuf 
flock 
frm 
fsalloc 
fsinf 
dosfsrs 
fsts 
ftime 
gis 
htype 
kbci 
kbstkbs 
kbxl 


1.3.2 Constant Names 


kbdtyp 
Inctl 

lis 
mdmst 
mnin 
mnout 
mouev 
moupl 
moups 
mouqdi 
mourt 
mousc 
trekfmt 
mxs 
mxsl 
rxq 
avpblick 
pidi 
nmpinf 


pi 
ptrdfnc 


ptbuf 
driv 
qresc 
resc 
shftst 
kbsi 
htky 
stdata 
mnpos 
stsdata 
rtdly 
vioci 
viofi 
vioin 
vioint 
viorni 
vioos 
viopal 
viopb 
vol 


A constant name is a descriptive name for a numeric value used with an MS 
OS/2 function. All constant names are written in uppercase letters and have a 
prefix derived from the name of the function, object, or idea associated with the 
constant. The prefix is followed by an underscore (_) and the rest of the con- 
stant name, which indicates the meaning of the constant and may specify a 
value, action, color, or condition. A few common constants do not have pre- 
fixes—for example, NULL is used for null pointers of all types, and TRUE and 
FALSE are used with the BOOL data type. 
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1.4 Notational Conventions 


The following notational conventions are used throughout this manual: 


Convention 


bold 


italics 


monospace 


Meaning | 


Bold type is used for keywords—for example, the 
names of functions, data types, structures, and 
macros. These names are spelled exactly as they 
should appear in source programs. 


Italic type is used to indicate the name of an 
argument; this name must be replaced by an 
actual argument. Italics are also used to show 
emphasis in text. 


Monospace type is used for example program- 
code fragments. 
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Functions Directory 
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2.1 Introduction 


This chapter describes MS OS/2 Dos, Kbd, Mou, and Vio functions. These 
functions, also called MS OS/2 base system functions, provide the support pro- 
grams need to access the basic operating-system features of MS OS/2, such as 
multitasking, memory management, and input and output. The Dos, Kbd, Mou, 
and Vio functions represent four distinct function groups. As described in the 
following list, programs use these function groups to carry out specific tasks: 


Function group Usage 


Dos Use the disk operating system (Dos) functions in 
full-screen and Presentation Manager sessions to 
read from and write to disk files, to allocate 
memory, to start threads and processes, to com- 
municate with other processes, and to access 
your computer’s devices directly. Most functions 
in this group can be used in Presentation 
Manager applications. 


Kbd Use the keyboard (Kbd) functions in full-screen 
sessions to read keystrokes from the keyboard, 
to manage multiple logical keyboards, and to 
change code pages and translation tables. Since 
the Presentation Manager session provides its 
own keyboard support, Kbd functions are not 
needed in Presentation Manager applications. 


Mou Use the mouse (Mou) functions in full-screen 
sessions to read mouse input from the mouse- 
event queue, to set the mouse-pointer shape, and 
to manage the mouse for all processes in a ses- 
sion. As with the keyboard, the Presentation 
Manager session provides its own mouse support, 
so Mou functions are not needed in Presentation 
Manager applications. 


Vio Use the video input-and-output (Vio) functions in 
full-screen sessions to write characters and char- 
acter attributes to the screen, to create pop-up 
windows for messages, to change the video 
modes, and to access physical video memory. 
Vio functions can also be used in advanced 
video-input-and-output (AVIO) applications for 
the Presentation Manager session to write charac- 
ters and character attributes in a window. Most 
Presentation Manager applications, however, use 
the graphics programming interface (Gpi) to 

' write text in a window. 


Many functions in this chapter are also family API functions. This means they 
can be used in dual-mode programs—that is, programs that run in either MS 
OS/2 or MS-DOS®. The family API functions are clearly marked. 


In this chapter, complete syntax, purpose, and parameter descriptions are given 
for each function. Types, macros, and structures used by a function are given 
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with the function; these are defined more fully in Chapter 4, “Types, Macros, 
Structures.” The numeric values for error values returned by the functions are 
listed in Appendix A, “Error Values.” 


Many of the function descriptions in this chapter include examples. The exam- 
ples show how to use the functions to accomplish simple tasks. In nearly all 
cases, the examples are code fragments, not complete programs. A code frag- 
ment is intended to show the context in which a function can be used, but often 
assumes that variables, structures, and constants used in the example have been 

_ defined and/or initialized. Also, a code fragment may use comments to represent 
a task instead of giving the actual statements. 


Although the examples are not complete, you can still use them in your pro- 
grams if you take the following steps: 
@ Include the os2.h file in your program. 


@ Define the appropriate include constants for the functions, structures, and 
constants used in the example. 


@ Define and initialize all variables. 
@ Replace comments that represent tasks with appropriate statements. 
™@ Check return values for errors and take appropriate actions. 


2.2 Functions 


The following is a complete list, in alphabetical order, of the MS OS/2 Dos, 
Kbd, Mou, and Vio functions. 
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HH DosAllocHuge 


USHORT DosAllocHuge(usNumSeg, usPartialSeg, psel, usMaxNumSeg, fsAlloc) 


USHORT usNumSeg; . /« number of segments to allocate »/ 
USHORT usPartia/lSeg; /« number of bytes in last segment »/ 
PSEL pse/; /« pointer to variable for selector allocated »/ 
USHORT usMaxNumSeg; /« maximum number of segments to reallocate «/ 
USHORT fsAlloc; /» sharable/discardable flags »/ 


The DosAllocHuge function allocates a huge memory block. This block consists 
of one or more 65,536-byte memory segments and one additional segment of the 
size specified by the usPartialSeg parameter. 


The DosAllocHuge function allocates the segments and copies the selector of 
the first segment to the variable pointed to by the psel parameter. Selectors for 
the remaining segments are consecutive and must be computed by using the 
selector offset. 


The DosAllocHuge function can specify that segments be sharable or discard- 
able. If the process that calls DosAllocHuge specifies that the segments can be 
shared, then it can call the DosGiveSeg function to make the location or the 
allocated segments available to another process. The other process must use the 
DosGetSeg function to access the shared memory. For more information about 
sharable and discardable segments, see the “Comments” section under the 
DosAllocSeg function. 


The DosAllocHuge function is a family API function. 


Parameters usNumSeg Specifies the number of 65,536-byte segments to be allocated. 


usPartialSeg Specifies the number of bytes in the last segment. This number 
can be any value from 0 through 65,535. If it is zero, no additional segment is 
allocated. 


psel Points to the variable that receives the selector of the first segment. 


usMaxNumSeg Specifies the maximum number of segments that can be 

. Specified in any subsequent call to the DosReallocHuge function. If the usMax- 
NumSeg parameter is zero, the memory cannot be reallocated to a size greater 
than its original size, but it can be reallocated to a smaller size. 


fsAlloc Specifies whether the segments can be shared with other processes or 
can be discarded. The fsAlloc parameter can be one or more of the following 


values: 

Value Meaning 

SEG_DISCARDABLE Create discardable segments. 

SEG_GETTABLE Create sharable segments that other processes can 
retrieve by using the DosGetSeg function. 

SEG_GIVEABLE Create sharable segments that the owning process 
can give to other processes by using the Dos- 
GiveSeg function. 

SEG_NONSHARED Create nonsharable, nondiscardable segments. 
This value cannot be combined with any other 
value. 


_If the shared or discardable attributes are not specified, only the process that 
creates the segment can access it, and the contents of the segment remain in 
memory until the process frees the segment. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_NOT_ENOUGH_MEMORY 


Comments Each segment in the huge memory block has a unique selector. The selectors are 
consecutive. The psel parameter specifies the value of the first selector; the 
remaining selectors can be computed by adding the selector offset to the first 
selector one or more times—that is, once for the second selector, twice for the 
third, and so on. The selector offset is a multiple of 2, as specified by the shift 
count retrieved by using the DosGetHugeShift function. For example, if the shift 
count is 2, the selector offset is 4 (1 << 2). If the selector offset is 4 and the 
first selector is 6, then the second selector is 10, the third is 14, and so on. 


The system may move or swap the memory segments as directed by the mem- 
man command in the config.sys file. Moving and swapping have no effect on the 
value of the segment selectors, so you can compute the selectors at any time and 
save them; they will remain available for use as long as the memory remains allo- 
cated. . 


The DosAllocHugeSeg function automatically locks the segment. A locked seg- 
ment cannot be discarded. You must use the DosUnlockSeg function to unlock 
the segment and permit discarding. To prevent the memory manager from dis- 
carding an unlocked discardable segment, use the DosLockSeg function. 


The DosFreeSeg function frees all segments if you pass it the first selector. 


Restrictions In real mode, the following restrictions apply to the DosAllocHuge function: 


@ The usPartialSeg parameter is rounded up to the next paragraph (16-byte) 
value. 


m™ The actual segment address is copied to the psel parameter. 
Example This example calls the DosAllocHuge function to allocate two segments with 64K 


and one segment with 200 bytes. It then converts the first selector to a huge 
pointer that can access all the memory allocated. 


CHAR huge *pchBuffer; 


SEL sel; 
DosAllocHuge (3, 7/* number of segments */ 
/* size of last segment */ 
&sel, /* address of selector */ 
5, 7* maximum segments for reallocation */ 
SEG_NONSHARED) ; /* sharing flag */ 
pchBuffer = MAKEP(sel, 0); /* converts to a pointer */ 
See Also DosAllocSeg, DosFreeSeg, DosGetHugeShift, DosGetSeg, DosGiveSeg, 


DosLockSeg, DosReallocHuge, DosUnlockSeg 


DosAllocSeg it | 
USHORT DosAllocSeg(usSize, psel, fsAlloc) 

USHORT usSize; /» number of bytes requested »/ 
PSEL pse?l; . /« pointer to variable for selector allocated »/ 
USHORT fsAlloc; _/« sharable/discardable flags »/ 


The DosAllocSeg function allocates a memory segment and copies the segment 
selector to the variable pointed to by the psel parameter. The segment can have 
from 1 through 65,536 bytes. 


Parameters 


Return Value 


Comments 
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The DosAllocSeg function can specify that the segment be sharable or discard- 
able. If the process that calls DosAllocSeg specifies that the segments can be 
shared, then it can call the DosGiveSeg function to make the location or the 
allocated segments available to another process. The other process must use the 
DosGetSeg function to access the shared memory. 


The DosAllocSeg function is a family API function. 

usSize Specifies the number of bytes to be allocated. This number can be any 
value from 0 through 65,535. If it is zero, the function allocates 65,536 bytes. 
psel Points to the variable that receives the segment selector. 


fsAlloc Specifies whether the segment can be shared with other processes or 
can be discarded. The fsAlloc parameter can be one or more of the following 
values: 


Value Meaning 

SEG_DISCARDABLE Create a discardable segment. 

SEG_GETTABLE Create a sharable segment that other processes 
can retrieve by using the DosGetSeg function. 

SEG_GIVEABLE Create a sharable segment that the owning pro- 


cess can give to other processes by using the Dos- 
GiveSeg function. 


SEG_NONSHARED Create a nonsharable, nondiscardable segment. 
This value cannot be combined with any other 
value. 


If the sharable or discardable attributes are not specified, only the process that 
creates the segment can access it, and the contents of the segment remain in 
memory until the process frees the segment. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_NOT_ENOUGH_MEMORY 


The system may move or swap the memory segment as directed by the memman 
command in the config.sys file. Moving and swapping have no effect on the seg- 
ment selectors. 


A sharable segment is available to the process that created it and to other pro- 
cesses. If necessary, the system will discard an unlocked discardable segment in 
order to satisfy another allocation request. The new allocation request can come 
from any process, including the process that allocated the segment being dis- 
carded. 


Discardable segments are useful for holding information that is accessed for 
short periods of time and that can be regenerated quickly if discarded. Examples 
are cache buffers for a database package, saved bitmap images for obscured win- 
dows, and precomputed display images for a word-processing application. 
Although the data in the segment is lost when the segment is discarded, the seg- 
ment can be restored to its original size by using the DosReallocSeg function. 


The DosAllocSeg function automatically locks the segment. A locked segment 
cannot be discarded. You must use the DosUnlockSeg function to unlock the 
segment and permit discarding. To prevent the memory manager from discarding 
an unlocked discardable segment, use the DosLockSeg function. 


The DosFreeSeg function frees the segment. 
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Restrictions 


Example 


See Also 


‘In real mode, the following restrictions apply to the DosAllocSeg function: 


m The usSize parameter is rounded up to the next paragraph (16-byte) 
value. 


™ The actual segment address is copied to the psel parameter. 


This example calls the DosAllocSeg function to allocate 26,953 bytes. It then 
converts the selector to a far pointer that can access the allocated bytes. 


PCH pcohBuffer; 


SEL sel; 
Deere eae tes /* bytes to allocate 
&sel, /* address of selector */ 
SEG_NONSHARED) ; /* sharing flag * 
pohBuffer = MAKEP (sel, O); /* converts to a pointer */ 


DosAllocHuge, DosFreeSeg, DosGetSeg, DosGiveSeg, DosLockSeg, 
DosReallocSeg, DosUnlockSeg 


DosAllocShrSeg 


USHORT usSize; 


USHORT DosAllocShrSeg({ usSize, pszSegName, psel) 
/« number of bytes requested x/ 
/x pointer to segment name »/ 


PSZ pszSegName; 


PSEL psel; 


Parameters 


Return Value 


/« pointer to variable for selector allocated «/ 


The DosAllocShrSeg function allocates a shared memory segment and copies the 
segment selector to the variable pointed to by the psel parameter. The segment 
can have from 1 through 65,536 bytes. 


A shared segment can be accessed by any process that knows the segment name. 
A process can retrieve a selector for the segment by specifying the name in a 
call to the DosGetShrSeg function. (Shared segments allocated by using the 
DosAllocSeg function must be explicitly given and retrieved by using the Dos- 
GiveSeg and DosGetSeg functions.) 


usSize Specifies the number of bytes to be allocated. This number can be any 
value from 0 through 65,535. If it is zero, the function allocates 65,536 bytes. 


pszSegName Points to a null-terminated string that identifies the shared mem- 
ory segment. The string must have the sonowag form: 


\sharemem\name 


The segment name, name, must have the same format as an MS OS/2 filename 
and must be unique. For example, the name eee a dat is accept- 
able. 


psel Points to the variable that receives the segment selector. 


The return value is zero if.the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ALREADY_EXISTS 
ERROR_INVALID_HANDLE 
ERROR_NOT_ENOUGH_MEMORY 
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Comments A process may allocate up to 30 shared segments. 


The system may move or swap the memory segments as directed by the mem- 
man command in the config.sys file. Moving and swapping have no effect on the 
value of the segment selector. 


The DosFreeSeg function frees a shared segment. 
Example This example calls the DosAllocShrSeg function to allocate 26,953 bytes. It gives 


the memory the name “\sharemem\abc.mem” so that other processes may use 
the memory if they know the name. 


SEL sel; 

DosAllocShrSeg (26953, /* bytes to allocate */ 
"\\sharemem\\abc.mem", /* memory name * 
&sel) ; /* address of selector */ 

See Also DosAllocHuge, DosAllocSeg, DosFreeSeg, DosGetSeg, DosGetShrSeg, Dos- 
GiveSeg 

DosBeep 

USHORT DosBeep(usFrequency, usDuration) 

USHORT usFrequency; /« frequency in hertz »/ 

USHORT usDuration; /« duration in milliseconds »/ 

The DosBeep function generates sound from the speaker. 
The DosBeep function is a family API function. 

Parameters usFrequency Specifies the frequency of the sound in hertz (cycles-per- 
second). This parameter can be any value from 0x0025 through Ox7FFF. 
usDuration Specifies the length of the sound in milliseconds. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 

ERROR_INVALID_FREQUENCY 

Example This example calls the DosBeep function and produces audible tones: 
SHORT i; 
for (i = 0; 4 < 10; i++) £ 

DosBeep (600, 175); : 
DosBeep (1200, 175); 
} 
See Also WinAlarm 
DosBufReset 


USHORT DosBufReset (hf) 
HFILE hf; /s file handle «/ 


The DosBufReset function flushes the file buffers for the specified file by writing 
the current contents of the file buffer to the corresponding device. If the file is a 
disk file, the function writes to the disk and updates the directory information 
for the file. 
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Parameters 


Return Value 


Comments 


Example 


See Also 


DosCallback 


Although DosBufReset flushes and updates information as if the file were 
closed, the file remains open. 


The DosBufReset function is a family API function. 


hf Identifies the file whose buffers are flushed. This handle must have been 
created previously by using the DosOpen function. If this parameter is set to 
OxFFFF, the function flushes buffers for all currently open files. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_FILE_NOT_FOUND 
ERROR_LINVALID_HANDLE 


If the process has several open files on removeable disks, the function may have 
the effect of requiring the user to repeatedly swap disks. 


_ This example opens the file abc and writes the contents of the abBuf buffer to 


the file. It then writes the data to the disk by calling the DosBufReset function 
to flush the buffers. 


BYTE abBuf [512]; 

HFILE hf; 

USHORT usAction, cbBytesWritten, usError; 

usError = DosOpen("abc", &hf, G&usAction, OL, FILE_NORMAL, 
FILE_CREATE | FILE_OPEN, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, OL); 

if (!usError) 
DosWrite(hf, abBuf, sizeof (abBuf), mehpycesnri tren): 
DosBu fReset (hf) ; /* flush the buffers s/ 


DosClose, DosOpen, DosWrite 


VOID DosCallback ( pfn) 
PEN pfn; /s pointer to ring-3 function »/ 


Parameters 
Return Value 
Comments 


The DosCallback function allows a process with ring-2 input/output privilege to 
call a ring-3 function. 


pfn Points to the ring-3 function to be called. 
This function does not return a value. 


When a process with ring—2 input/output privileges uses the DosCallback func- 
tion to call a ring-3 function, the target function executes at ring 3 and returns to 
the ring—2 calling process. The ring-3 function need not conform to the ring-2 
privilege level. The ring-3 function that is called by the DosCallback function 
may call a ring-2 segment before it returns. 


All registers except FLAGS will be passed intact across this call/return sequence 
and may be used to pass parameters or data back and forth between rings 2 and 
3. Any addresses passed from ring 2 to ring 3 must be based on ring-3 selectors, 
because ring-3 code cannot address ring—2 data selectors. 


A ring-2 stack cannot be used to pass data to a ring-3 function. 
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DosCaliNmPipe 


The following Dos functions are valid when issued from ring 2: 


DosAllocHuge 
DosAllocSeg 
DosAllocShrSeg 
DosBeep 
DosBufReset 
DosCallback 
DosChDir 
DosChgFilePtr 
DosCliAccess 
DosClose 
DosCloseSem 
DosCreateCSAlias 
DosCreateSem 
DosCreateThread 
DosCwait 
DosDelete 
DosDevConfig 
DosDeviIOCtl 
DosDupHandle 
DosEnterCritSec 
DosErrClass 
DosError 
DosExecPgm 
DosExit 
DosExitCritSec 
DosExitList 
DosFileLocks 
DosFindClose 
DosFindFirst 
DosFindNext 
DosFlagProcess 
DosFreeModule 
DosFreeSeg 


DosFSRamSemClear 
DosFSRamSemRequest 


DosGetCp 
DosGetDateTime 
DosGetEnvy 


DosGetHugeShift 
DosGetInfoSeg 


DosGetMachineMode 
DosGetModHandle 


DosGetModName 
DosGetPID 
DosGetPPID 
DosGetProcAddr 
DosGetPrty 
DosGetResource 
DosGetSeg 
DosGetShrSeg 
DosGetVersion 
DosGiveSeg 
DosHoldSignal 
DosKillProcess 
DosLoadModule 
DosLockSeg 
DosMakePipe 
DosMemAvail 
DosMkDir 
DosMove 
DosMuxSemWait 
DosNewSize 
DosOpen 
DosOpenSem 
DosPhysicalDisk 
DosPortAccess 
DosQAppType 
DosQCurDir 
DosQCurDisk 
DosQFHandState 
DosQFileInfo 
DosQFileMode 
DosQFSInfo 
DosQHandType 
DosQVerify 
DosRead 


DosReadAsync 
DosReallocHuge 
DosReallocSeg 
DosResumeThread 
DosRmDir 
DosScanEny 
DosSearchPath 
DosSelectDisk 
DosSemClear 
DosSemRequest 
DosSemSet 
DosSemSetWait 
DosSemWait 
DosSendSignal 
DosSetCp 
DosSetDateTime 
DosSetFHandState 
DosSetFileInfo 
DosSetFileMode 
DosSetFSInfo 
DosSetMaxFH 
DosSetPrty 
DosSetSigHandler 
DosSetVec 
DosSetVerify 
DosSizeSeg 
DosSleep 
DosSubAlloc 
DosSubFree 
DosSubSet 
DosSuspendThread 
DosTimerAsyne 


‘DosTimerStart 


DosTimerStop 
DosUnlockSeg 
DosWrite 
DosWriteAsyne 


USHORT DosCaliNmPipe(pszName, pbinBuf, cbinBuf, pbOutBuf, cbOutBuf, pcbRead, ulTimeOut) 


PSZ pszName; 
PBYTE pbinBuf; 
USHORT cbinBuf; 
PBYTE pbOutBuf, 
USHORT cbOutBuf; 


PUSHORT pcbRead; 


ULONG u/TimeOut; 


/»« pointer to pipe name 
/« pointer to input buffer 


»/ 
s/ 


/»« number of bytes in input buffer — «/ 


/« pointer to output buffer 


x/ 


/« number of bytes in output buffer «/ 
/« pointer to variable for bytes read «/ 


/« timeout value 


The DosCallNmPipe function opens a named pipe, writes to and reads from it, 


and closes it. 


»/ 
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Parameters 


Return Value 


Comments 


See Also 


DosCaseMap 


pszName Points to the name of the pipe. The name is in the form \pipe\name 
for a local pipe and \\server\pipe\name for a remote pipe. 


pbInBuf Points to the buffer containing the data that is written to the pipe. 
cbInBuf Specifies the size (in bytes) of the input buffer. 


pbOutBuf Points to the output buffer that receives the data read from the 
pipe. 

cbOutBuf Specifies the size (in bytes) of the output buffer. 

pcbRead Points to the variable that receives the number of bytes read from 
the pipe. 


ulTimeOut Specifies a value (in milliseconds) that is the amount of time MS 
OS/2 should wait for the pipe to become available. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_INTERRUPT 
ERROR_INVALID_FUNCTION 
ERROR_SEM_TIMEOUT 


The DosCallNmPipe function is equivalent to calling DosOpen, DosTransact- 
NmPipe, and DosClose. | 


DosMakePipe, DosTransactNmPipe 


USHORT DosCaseMap(usLength, pctryc, pchString) 


USHORT usLength; 


/« length of string to casemap »/ 


PCOUNTRYCODE pctryc; /« pointer to structure for country code «/ 


PCHAR pchString; 


Parameters 


/« pointer to character string »/ 


The DosCaseMap function casemaps the characters in the given string. If neces- 
sary, the function replaces characters in the string with the correct case-mapped 


Characters. 


The DosCaseMap function uses the casemap information in the country.sys file 
to casemap the string. 


The DosCaseMap function is a family API function. 


usLength Specifies the length of the given string. 


petryc Points to the COUNTRYCODE structure that contains the country 
code and the code-page identifier for the casemap operation. The COUN- 
TRYCODE structure has the following form: 


typedef struct _COUNTRYCODE { 
USHORT country; 
USHORT codepage; 

} COUNTRYCODE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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pcehString Points to the character string to be casemapped. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


-ERROR_NLS_BAD_TYPE 
ERROR_NLS_NO_COUNTRY_FILE 
ERROR_NLS_NO_CTRY_CODE 
ERROR_NLS_OPEN_FAILED 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_TYPE_NOT_FOUND 


Restrictions In real mode, the following restriction applies to the DosCaseMap function: 


@ There is no method of identifying the boot drive. The system assumes 
that the country.sys file is in the root directory of the current drive. 


See Also DosGetCollate, DosGetCtryInfo, DosSetCp 
DosChDir 

USHORT DosChDir( pszDirPath, ulReserved) 

PSZ pszDirPath; /« directory path «/ 


ULONG ul/Reserved; /x must be zero. «/ 


The DosChDir function changes the current directory to the specified directory. 
When a process changes the current directory, subsequent calls to file-system 
functions, such as the DosOpen function, use the new directory as the default 
directory. The default directory is used if no explicit path is given with a 
filename. 


The DosChDir function is a family API function. 


Parameters pszDirPath | Points to the null-terminated string that specifies the new directory 
path. The string must be a valid MS OS/2 directory path and must not be longer 
than 125 characters. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Dee: it is an error 
value, which may be one of the following: 


ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_PATH_NOT_FOUND 
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Comments 


Example 


See Also 


DosChgFilePtr 


This function applies only to the process that is changing the directory. It does 
not affect the current directories of other processes. When the process termi- 
nates, the previous default directory becomes the default directory again. 

When a process starts, it inherits its current directory from the parent process. 
This example stores the current default drive and path, then calls the DosChDir 
function to change the default path to the root ECO: 

PSZ pszPath; 

USHORT cbPath = O, webiee: 

ULONG ulLogicalDrives; 

SEL selPath; 


DosQCurDisk(&usDisk, &ulLogicalDrives) ; /* gets current drive */ 


DosQCurDir (usDisk, NULL, &cbPath) ; 7* gets size of buffer */ 
DosAllocSeg(cbhPath, &selPath, SEG_NONSHARED); /* allocates memory 

pszPath = MAKEP(selPath, 0); /* assigns it to a far pointer */ 
DosQCurDir (usDisk, pszPath, &cbPath); /* gets current directory x/ 
DosChDir ("\\", OL); /* changes to the root directory */ 
DosChDir(pszPath, OL); /* restores the directory */ 


DosMkDir, DosQCurDir, DosQCurDisk, DosRmDir, DosSelectDisk 


USHORT DosChgFilePtr(hf, /Distance, fMethoa, Coe 


HFILE hf; 

LONG /Distance; 
USHORT fMethoa; 
PULONG pu/NewPrtr, 


Parameters 


/ file handle »/ 
/» distance to move —«/ 
/« method of moving «/ 
/» new pointer location »/ 


The DosChgFilePtr function moves the file pointer to a new position in the file. 
The file pointer is maintained by the system. It points to the next byte to be read 
from a file or to the next position in the file to receive a byte. 


The DosChgFilePtr function is a family API function. 
hf Identifies the file. This handle must have been created previously by using 
the DosOpen function. 


IDistance Specifies the number of bytes to move the file pointer in the file. If 
this value is positive, the pointer moves forward through: the file. If the value i is 
negative, the pointer moves backward. 


{Method Specifies where the move will start. This parameter must be one of 
the following values: 


Value meaning 

FILE_ BEGIN Start move at the beginning of the file. 
FILE_ CURRENT Start move at the current location. 
FILE_END Start move at the end of the file. 


pulNewPtr Points to the long variable that receives the new file-pointer loca- 
tion. aT, Oe a 
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Return Value The return value is zero if the function is successful. Ole nNise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_FUNCTION 
ERROR_LINVALID_HANDLE 


Comments The system automatically advances the file pointer for each byte read or written; 
the pointer is at the beginning of the file when the file is opened. 


Example This example opens the file abc for read and write access, calls the DosChg- 
FilePtr function to set the file pointer at the end of the file, writes the string 
“Hello World”, and closes the file. The ulFilePointer variable contains the file’s 
current length when the pointer is at the end of the file. 


HFILE hf; 

USHORT usAction, cbBytesWritten; 

ULONG ulFilePointer; 

DosOpen("abc", &hf, &usAction, OL, FILE_NORMAL, 
FILE_OPEN | FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, OL); 


DosChgFilePtr (hf, /* file handle */ 
OL, /* distance to move a/ 
FILE_END, /* type of movement */ 
&ulFilePointer) ; /* address of new position */ 


DosWrite(hf, "Hello World\r\n", 13, &cbBytesWritten) ; 
DosClose (hf) ; 


See Also DosNewSize, DosOpen, DosRead, DosWrite 


DosCLliAccess 
USHORT DosCLliAccess(VO/D) 


The DosCLIAccess function requests an japuw/oatput (I/O) privilege for dis- 
abling and enabling interrupts. Assembly-language programs that use the cli and 
sti instructions in IOPL segments must use the DosCLiAccess function to 
receive permission to use these instructions. 


The DosCLIAccess function is a family API function. 
This function has no parameters. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments Assembly-language programs that use the in and out instructions to read from 


and write to I/O ports must use the DosPortAccess function to receive permis- 
sion to use these instructions. The DosPortAccess function also grants permis- 
sion to use the cli and sti instructions. 


See Also DosPortAccess 


28 - DosClose 


DosClose 


USHORT DosClose (hf) 
HFILE hf; /« file handle «/ 


Parameters 


Return Value 


The DosClose function closes a specified file or pipe. DosClose causes the sys- 
tem to write the contents of all the file’s internal buffers to the device—for exam- 
ple, to the disk—and to update all directory information. 


The DosClose function is a family API function. 


hf Identifies the file to close. This handle must have been created previously 
by using the DosOpen function, the DosDupHandle function, or the Dos- 
MakePipe function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_FILE_NOT_FOUND 
ERROR_INVALID_HANDLE 


Return Value 


Example This example opens the file abc, reads from the file, and calls the DosClose 
function to close it: 
BYTE abBuf[512]; 
HFILE hf; 
USHORT usAction, cbhBytesRead; 
DosOpen("“abe", &hf, &usAction, OL, FILE_NORMAL, FILE_OPEN, 

OPEN_ACCESS_READONLY | OPEN_SHARE_DENYNONE, OL); 
DosRead(hf, abBuf, sizeof (abBuf), &cbBytesRead) ; 
DosClose (hf) ; /* closes the file */ 
- See Also DosBufReset, DosDupHandle, DosFindClose, DosMakePipe, DosOpen, 

DosRead 

DosCloseQueue 

USHORT DosCloseQueue ( hqueue) 

HQUEUE hqueue; /« queue handle «/ 
The DosCloseQueue function closes a queue. If the process calling DosClose- 
Queue owns the queue, the function removes any outstanding elements from the 
queue. If the process does not own the queue, the contents of the queue remain 
unchanged and the queue remains available to other processes that have it open. 

Parameters hqueue Identifies the queue to be closed. This queue must have been pre- 


viously created or opened by using the DosCreateQueue or DosOpenQueue 
function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_QUE_INVALID_HANDLE 


Comments 


Example 


See Also 


DosCloseSem 
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After the owner closes the queue, any process that attempts to write to the 
queue will receive an error value. 


This example creates and opens a queue, then calls the DosCloseQueue function 
to close the queue: 


HQUEUE hqueue; 
DosCreateQueue (&hqueve, QUE_FIFO, "\\queues\\abc. que") ; 


DosCloseQueue (hqueue) ; 


DosCreateQueue, DosOpenQueue, DosReadQueue, DosWriteQueue 


USHORT DosCloseSem(hsem) 


HSEM hsem; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/« semaphore handle «/ 


The DosCloseSem function closes a specified system semaphore. If another pro- 
cess has the semaphore open, it remains open and can be used by that process, 
although the semaphore cannot be used by the process that closes it. This func- 
tion deletes the semaphore only when the last process using the semaphore 
closes it. 


hsem Identifies the semaphore to be closed. This handle must have been 
previously created or opened by using the DosCreateSem or DosOpenSem 
function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_HANDLE 
ERROR_SEM_IS_SET 


If a process does not close its semaphores before terminating, the system closes 
them. 


This example opens a previously created system semaphore, then calls the Dos- 
CloseSem function to close it: 


HSEM hsem; /* semaphore handle / 
DosOpenSem(&hsem, "\\sem\\abc") ; /* opens the semaphore */ 
DosCloseSem (hsem) ; . /* closes the semaphore */ 


DosCreateSem, DosOpenSem 


sConnectNmPipe 


ConnectNmPipe | 
ORT DosConnectNmPipe (hp) 


PIPE hp; / pipe handle «/ 


The DosConnectNmPipe function waits for a client to open a named pipe. 


Parameters hp Identifies the named pipe. This handle must have been created previously 
by using DosMakeNmPipe. — 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_BROKEN_PIPE 
ERROR_LINTERRUPT 
ERROR_LINVALID_FUNCTION 
ERROR_PIPE_NOT_CONNECTED 


Comments If the client end of a named pipe is open, the DosConnectNmPipe function 
returns immediately. If the client end of a named pipe is not open and the pipe 
was created with blocking, the DosConnectNmPipe function waits until a client 
opens the pipe. If the client end of a named pipe is not open and the pipe was 
created with no blocking, the DosConnectNmPipe function returns an error 
value immediately. 


In nonblocking mode, multiple DosConnectNmPipe calls can be issued to poll 

the state of a named pipe. If a client has not opened the pipe, the first call to the 
DosConnectNmPipe function puts the named pipe into a listening state and 
returns immediately with an ERROR_PIPE_LNOT_CONNECTED return value. 
Subsequent calls to the DosConnectNmPipe function also return this error 
value, until a client opens the named pipe. 


If a named pipe was opened and closed by a client but has not been discon- 
nected by the controlling process, the DosConnectNmPipe function returns 
ERROR_BROKEN_PIPE. 


See Also DosDisConnectNmPipe, DosMakeNmPipe | 


DosCreateCSAlias 


USHORT DosCreateCSAlias(se/DataSegment, pselCodeSegment) 
SEL se/DataSegment; /« data-segment selector xf 
PSEL pse/CodeSegment; /x pointer to code-segment selector +/ 


The DosCreateCSAlias function creates an aliased code-segment selector for a 
specified memory segment. The aliased code-segment selector can be used to 
pass execution control to machine instructions in a data segment. 


The DosCreateCSAlias function is a family API function. 
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Parameters selDataSegment Specifies the data-segment selector that identifies the mem- 
ory segment. 


pselCodeSegment Points to the variable that receives the aliased code- 
segment selector. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_ACCESS_DENIED 


Comments Shared memory segments, segments in huge memory blocks, and global data 
segments from dynamic-link libraries cannot be used to create an aliased code 
segment. 


If the process has copied valid machine instructions to the data segment, the 
aliased code-segment selector can be combined with a segment offset to pass 
execution control to the machine instructions. The instructions in the aliased 
code segment can be called from either privilege level 2 (input/output privilege) 
or privilege level 3. 


The DosFreeSeg function frees the aliased code-segment selector. Freeing the 
data-segment selector does not affect the aliased code segment, or vice versa. 
The segment is not removed from memory until both selectors have been freed. 


Restrictions In real mode, the following restrictions apply to the DosCreateCSAlias function: 


@ The selector returned is the address of the code. 


™@ Freeing either the aliased selector or the original selector immediately 
frees the block of memory. 


See Also DosAllocSeg, DosFreeSeg 
DosCreateQueue 

USHORT DosCreate Queue ( phqueue, fQueueOrder, pszQueueName) 
PHQUEUE phqueue; /« pointer to variable for queue handle »/ 
USHORT fQueueOrder; /» order in which elements are read-written »/ 
PSZ pszQueueName; /« pointer to queue name »/ 


The DosCreateQueue function creates and opens a queue. The new queue is 
owned by the process that calls the function, but can be opened for use by other 
processes. 


Parameters phqueue Points to the variable that receives the queue handle. 
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Return Value 


Comments 


See Also 


DosCreateSem 


fQueueOrder | Specifies the order in which elements are read from and written 
to the queue. This parameter can be one of the following values: 


Value Meaning 

QUE_FIFO First-in/first-out queue. The first element put in the 
queue is the first element to be removed. 

QUE_LIFO Last-in/first-out queue. The last element put in the 

queue is the first element to be removed. 

QUE_PRIORITY Priority queue. The process that places the element in 


the queue specifies a priority. Elements with the 
highest priority are removed first. 


pszQueueName Points to a null-terminated string. The string identifies the 
queue and must have the following form: 


\queues\name 


The string name, name, must have the same format as an MS OS/2 filename and 
must be unique. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_DUPLICATE 
ERROR_QUE_INVALID_NAME 
ERROR_QUE_INVALID_PRIORITY 
ERROR_QUE_NO_MEMORY 


The process that creates a queue owns that queue. The owning process can write 
elements to and read elements from the queue at any time, since DosCreate- 
Queue automatically opens the queue for the owning process. Other processes 
may open the queue by using the DosOpenQueue function and write elements to 
it by using the DosWriteQueue function, but they cannot read elements from the 
queue. Any thread belonging to the process that owns a queue can read from or 
write to the queue. 


If any process has a queue open when the owner closes it, subsequent requests 
to write to the queue return an error value. 


DosCloseQueue, DosOpenQueue 


USHORT DosCreateSem( fNoExclusive, phssm, pszSemName) 
USHORT fNoExclusive: /« exclusive/nonexclusive ownership flag ——«/ 


PHSYSSEM phssm; 
PSZ pszSemName; 


/« pointer to variable for semaphore handle «/ 
/x pointer to semaphore name a/ 


The DosCreateSem function creates a system semaphore and copies the sema- 
phore handle to a variable. A process can use a system semaphore to indicate to 
another process a change in the status of a shared resource. 


Parameters 


Return Value 


Comments 


Example 


See Also 
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fNoExclusive Specifies ownership of the semaphore. If this parameter is 
CSEM_PRIVATE, the process receives exclusive ownership. If this parameter is 
CSEM_PUBLIC, the process does not receive exclusive ownership. 


phssm Points to the variable that receives the semaphore handle. 


psgSemName Points to a null-terminated string that identifies the semaphore. 
The string must have the following form: 


\sem\Viame 


The string name, name, must have the same format as an MS OS/2 filename and 
must be unique. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ALREADY_EXISTS 
ERROR_INVALID_NAME 
ERROR_LINVALID_PARAMETER 
ERROR_TOO_MANY_SEMAPHORES 


The process that creates the system semaphore owns it. Other processes can 
open the semaphore by using the DosOpenSem function, then wait for a change 
in the status of the semaphore by using the DosSemWait or DosMuxSemWait 
function. The owning process can change the status of the semaphore by using 
the DosSemSet or DosSemClear functions. 


The process calling the DosCreateSem function receives exclusive ownership of 
a system semaphore, unless otherwise specified. Exclusive ownership prevents 
other processes from setting or clearing the semaphore while the owning process 
has it open. Other processes may open the semaphore and wait for it to change 
status, but they cannot change its status. 


This example calls DosCreateSem to create a system semaphore, then calls Dos- 
SemSet to set it and DosSemClear to clear it: 


HSYSSEM hssm; * handle to semaphore */ 
DosCreateSem(CSEM_PRIVATE, /* specifies ownership */ 

&hssm, /* address of handle */ 
"\\sem\\abc.sem") ; /* name of semaphore */ 
DosSemSet (hssm) ; /* sets the semaphore */ 
DosSemClear (hssm) ; /* clears the semaphore */ 


DosCloseSem, DosOpenSem, DosSemClear, DosSemRequest, DosSemSet, 
DosSemSetWait, DosSemWait 
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HM DosCreateThread 


USHORT DosCreateThread( pfnFunction, ptidThread, pbThrdStack) 
PFNTHREAD pfnFunction(VOID); /» pointer to address of function »/ 


PTID ptidThread; 


PBYTE pbThrdStack; 


Parameters 


Return Value 


Comments 


/« pointer to variable for thread identifier «/ 
/« pointer to thread stack »/ 


The DosCreateThread function creates a new thread. 


pfnFunction Points to a program-supplied function and represents the starting 
address of the thread. For a full description, see the following “Comments” sec- 
tion. 


ptidThread Points to the variable that receives the thread identifier. 
pbThrdStack Points to the address of the new thread’s stack. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NO_PROC_SLOTS 
ERROR_NOT_ENOUGH_MEMORY 


When a thread is created, the system makes a far call to the application-supplied 
function whose address is specified by the pfnFunction parameter. This function 
may include local variables and may call other functions, as long as the thread’s 


- stack has sufficient space. (The stack can be allocated by using the DosAllocSeg 


function or by using a global array.) The address specified by the pbThrdStack 
parameter should be the address of the last word in the stack, not the first, since 
the stack grows down in memory. The thread terminates when the function 
returns or calls the DosExit function. 


The pfnFunction parameter points to a function that is supplied by the program. 
This function should have the following form: 


VOID FAR FuncName (VOID) 
{ 
} 


Since the system passes no arguments, no parameters are defined. 


DosCreateThread can create up to 255 threads per process. A new thread inher- 
its all files and resources owned by the parent process. Any thread in a process 
can open a file, device, pipe, queue, or system semaphore. Other threads may 
use the corresponding handles to access the given item. 


Note that high-level-languages, run-time libraries, and stack checking may 
severely limit or eliminate the ability to call the DosCreateThread function 
directly from a high-level-language program. For more information, consult the 
documentation that came with your language product. 


Before calling the DosCreateThread function, either set the es register to zero 
or assign to it a selector that will remain valid for the duration of the new 
thread. If you fail to set the es register to one of these values, the thread may 
unexpectedly terminate as a result of a general protection fault. For more infor- 
mation, see the Microsoft Operating System/2 Programmer’s Reference, Volume 1. 


Example 


See Also 


DosCwait 
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This example sets aside a 512-byte buffer to be used as stack space for any 
threads that are created. The first stack is set at the end of the array. The thread 
is created by calling the DosCreateThread function. The thread terminates by 
calling the DosExit function. 


VOID FAR Threadi(); 
BYTE abStackArea [512]; 


PVOID pStackl = abStackArea + 512; /* $12-byte stack */ 

TID tidThreadi; 

DosCreateThread (Thread1, /* name of thread function */ 
&tidThreadi, /* address of thread ID */ 
pStack1); /* thread's stack * 


DosExit (EXIT_PROCESS, 0); 
} 


VOID FAR Threadi() { 


DosExit (EXIT_THREAD, 0); 


DosExit, DosResumeThread, DosSuspendThread 


USHORT DosCwait (fScope, fWait, prescResults, ppidProcess, pidWaitProcess) 


USHORT fScope; 
USHORT fWait; 


/« flag scope »/ 
/« wait/no-wait flag af 


PRESULTCODES prescResults; /« pointer to structure receiving result codes «/ 


PPID ppidProcess; 
PID pidWaitProcess; 


Parameters 


/« pointer to variable for process identifier — «/ 
/« process identifier of process to wait for —«/ 


The DosCwait function waits for a child process to terminate, then retrieves the 
result codes from that process. The function copies the process identifier of the 
terminated process to the variable pointed to by the ppidProcess parameter and 

copies a termination code to the structure pointed to by the prescResults param- 
eter. 


{Scope Specifies how many processes to wait for. If the value of this parame- 
ter is DCWA_PROCESS, the thread waits until the specified process ends. If it 
is DCWA_PROCESSTREE, the thread waits until the specified process and all 
its child processes end. | 


fWait Specifies whether or not to wait for child processes. If this parameter is 
DCWW_WAIT, the thread waits while child processes are running. If it is 
DCWW_NOWAIT, the thread does not wait. This option is used to retrieve the 
result codes of a child process that has already ended. 
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Return Value 


Comments 


Example 


See Also 


prescResults Points to the RESULTCODES structure that receives the 
termination code and result code for the child process’s termination. The 
RESULTCODES structure has the following form: 


typedef struct _RESULTCODES { 
USHORT codeTerminate; 
USHORT codeResult; 

} RESULTCODES; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


ppidProcess Points to the variable that receives the process identifier of the 
ending process. 


pidWaitProcess Specifies which process to wait for. If this parameter is a pro- 
cess identifier, the thread waits for that process to end. If it is zero, the thread 
waits until any child process ends. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_CHILD_NOT_COMPLETE 
ERROR_INVALID_PROCID 
ERROR_WAIT_NO_CHILDREN 


The DosCwait function may wait for a child process and any processes started 
by the child process to end before it returns, but it will not report the status of 
the processes that were started by the child process. 


When the function is waiting for more then one child process, the ppidProcess 
variable is used to determine which child process has terminated. 


Do not call the DosCwait function before starting a child process. When this 
happens, the process calling DosCwait waits indefinitely, since a child process 
cannot start asynchronously. 


This example runs the cmd.exe program as a child process, then calls the 
DosCwait function to wait until cmd.exe terminates: 


CHAR achFailName[128]; 

RESULTCODES rescResults; 

PID pidProcess; 

DosExecPgm(achFailName, sizeof (achFailName) , 


EXEC_ASYNC, "cmd ", 0, &rescResults, "cmd.exe") ; 

DosCwait (DCWA_PROCESS, /* execution flag s/ 
DCWW_WAIT, /* wait option */ 
&rescResults, /* address for result codes */ 
&pidProcess, * 


address of process identifier */ 
rescResults.codeTerminate); /* process to wait for * 


DosExecPgm, DosExit, DosKillProcess 
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HM DosDelete 


USHORT DosDelete(pszFileName, ulReserved) | 
PSZ pszFileName; /« pointer to string specifying pathname «/ 
ULONG u/Reserved; /« must be zero »/ 


The DosDelete function deletes a file. 
The DosDelete function is a family API function. 


Parameters pszFileName Points to a null-terminated string that specifies the file to be 
deleted. This string must be a valid MS OS/2 filename and must not contain 
wildcard characters. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 


Comments Read-only files cannot be deleted by using the DosDelete function. The DosSet- 
FileMode function can be used to change a file’s read-only attributes, making it 
possible to delete that file. 


The DosDelete function cannot delete directories; use the DosRmDir function to 
delete directories. 


Example This example calls the DosDelete function to delete the file abc, and displays a 
message reporting success or failure: 
USHORT usError; 
usError = DosDelete("abc", OL); 
if (usError) 
ViowWrtTITY ("abc not deleted\r\n", 21, 0); 
else 
VioWrtTTY ("abc deleted\r\n", 17, 0); 


See Also DosRmDir, DosSetFileMode 


—™ DosDevConfig 
USHORT DosDevConfig( pvDevinfo, usitem, usReserved) 


— PVOID pvDevinfo; /« pointer to variable for device information »/ 
USHORT usitem; /« item number »/ 
USHORT usReserved; _/« must be zero s/ 


The DosDevConfig function retrieves information about attached devices. 
The DosDevConfig function is a family API function. 
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Parameters pvDevInfo Points to the variable that receives device information. The type of 
information received depends on the value of the usItem parameter. 


usItem Specifies what device information to retrieve. This parameter can be 
one of the following values: 


Value Meaning 


DEVINFO_ADAPTER The pvDevinfo parameter points to a 
BYTE variable that is set to FALSE if the 
primary display adapter is a mono- 
chrome/printer display adapter type, or to 
TRUE for other display adapters. 


DEVINFO_COPROCESSOR The pvDevinfo parameter points to a 
BYTE variable that is set to TRUE if a 
math coprocessor is present. 

DEVINFO_FLOPPY The pvDevinfo parameter points to a 
USHORT variable that receives the num- 
ber of removeable-disk drives that are 


installed. 

DEVINFO_MODEL The pvDevinfo parameter points to a 
BYTE variable that receives the PC model 
type. 

DEVINFO_PRINTER The pvDevinfo parameter points to a 


USHORT variable that receives the num- 
ber of printers that are attached. 


DEVINFO_RS232 The pvDevinfo parameter points to a 
USHORT variable that receives the num- 
ber of RS232 cards that are attached. 

DEVINFO_SUBMODEL The pvDevinfo parameter points to a 


BYTE variable that receives the PC sub- 
model type. 


usReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_PARAMETER 


Example This example calls the DosDevConfig function to determine if a math coproces- 
sor is present: 


BYTE bDevinfo; 
DosDevConfig(&bDeviInfo, /7* address of variable for device info. */ 
DEVINFO_COPROCESSOR, /* information requested 
O); /* reserved */ 
if (bDevInfo) 
VioWrtTTY ("Math coprocessor present\r\n", 26, 0); 
else 
VioWrtTTY ("Math coprocessor not present\r\n", 30,. 0); 


See Also DosDevIOCtl, VioGetConfig 


M@ DosDeviO0Ctl 


USHORT DosDevi0OC 
PVOID pvData; 
PVOID pvParms; 
USHORT usFunction; 
USHORT usCategory; 
HFILE hDevice; 


Parameters 


Return Value 


Restrictions 
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tl( pvData, pvParms, usFunction, usCategory, hDevice) 


/« pointer to buffer for data area »/ 
/« pointer to buffer for command arguments »/ 
/« device function »/ 
/« device category »/ 
/« device handle »/ 


The DosDevIOCtl function passes device-control functions to the device 
specified by the hDevice parameter. 


The DosDevIOCtl function is a family API function. 


pvData Points to a buffer that receives data from the given control function. 
Some control functions may also read data from the buffer as part of their pro- 
cessing. 


pvParms Points to a buffer that contains any data required for the given con- 
trol function. Some control functions may copy data to the buffer as part of their 
processing. 


usFunction Specifies the device-control function. This parameter can be any 
one of the device-control function codes described in Chapter 3, “Input-and- 
Output Control Functions.” 


usCategory Specifies the device categories. This parameter can be any one of 
the device categories described in Chapter 3, “Input-and-Output Control Func- 
tions.” 


hDevice Identifies the device that receives the device-control function. This 
handle must have been created previously by using the DosOpen function or it 
must be a standard (open) device handle. 


In addition to the system error values, the DosDevIOCtl function returns device 
driver return-value information. Return values in the range OxFFO0O through 
OxFFFF are user-dependent error values. Return values in the range 0xFE0O 
through OxFEFF are device-driver-dependent error values. 


The error value may be one of the following: 


ERROR_BAD_DRIVER_LEVEL 
ERROR_LINVALID_CATEGORY 
ERROR_INVALID_DRIVE 
ERROR_LINVALID_FUNCTION 
ERROR_INVALID_HANDLE 
ERROR_PROTECTION_VIOLATION 


In real mode, the following restrictions apply to the DosDevIOCtl function: 


™ Some control functions in categories 1, 5, and 8 can be used with MS- 
DOS 3.x, but not with MS-DOS 2.x. 


@ Categories 2, 3, 4, 6, 7, 10, and 11 cannot be used. 
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Example — This example calls the DosDevIOCtl function to change the typamatic rate of the 
; keyboard. Before you can use the DosDevIOCtl function to access the keyboard 
you must open the keyboard device and set the focus. 


USHORT usParameters [2]; 
HKBD hkbd; 


usParameters[O] = 500; /* delay in milliseconds */ 
usParameters([1] = 60; /* characters per second */ 
KbdOpen (&hkbd) ; /* opens the keyboard a/ 
KbdGetFocus (0, hkbd) ; /* gets the focus a/ 
DosDevI0Ct1 (OL, /* data area */ 
.(PCHAR) usParameters, /* command arguments */ 
Ox54, /* function code */ 
4, /* device category */ 
hkbd) ; /* handle to device keyboard */ 
See Also DosOpen, KbdGetFocus, KbdOpen 


DosDisConnectNmPipe 


USHORT DosDisConnectNmPipe (hp) 
HPIPE hp; /« pipe handle »/ 


The DosDisConnectNmPipe function closes a client’s handle of a named pipe. 


Parameters hp Identifies the named pipe. This handle must have been created previously 
by using the DosMakeNmPipe function. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 
ERROR_BAD_PIPE 


ERROR_INVALID_FUNCTION 


Comments If the client end of a named pipe is open, the DosDisConnectNmPipe function 
forces that end of the named pipe closed. The client will receive an error value 
the next time it attempts to access the pipe. Closing the client end of a named 
pipe may discard data in the pipe before the client reads the data. 


A client that is forced off a pipe by a call to DosDisConnectNmPipe must still 
close its end of the pipe by using the DosClose function. 


See Also DosClose, DosConnectNmPipe, DosMakeNmPipe 
DosDupHandle 

USHORT DosDupHandle (hfO/d, phfNew) 

HFILE hfOld; /» handle of existing file «/ 


PHFILE phfNew; _—/« pointer to variable containing new file handle «/ 


The DosDupHandle function duplicates a file handle. The new handle has the 
same handle-specific information as the existing handle, such as its file-pointer 
position and access method. The original handle and the duplicate are inter- 
changeable, since most changes to one affect the other. For example, moving the 


Parameters 


Return Value 


Comments 


Example 


See Also 
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file pointer for the original handle moves the pointer for the new handle. Closing 
the original handle by using the DosClose function does not close the duplicate 
handle, however, and closing the duplicate does not close the original. A file is 
not closed until its last handle is closed. 


The DosDupHandle function is a family API function. 
hfOld Identifies the file handle to duplicate. This handle must have been 


created previously by using the DosOpen function. The DosDupHandle function 
closes the file before duplicating its handle. 


phfNew Points to the variable that contains the new file handle. If this param- 


eter is OxFFFF, the DosDupHandle function creates a new handle and copies it 
to the variable pointed to by the phfNew parameter. Any specified value other 
than OxFFFF is used as the handle. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_HANDLE 
ERROR_INVALID_TARGET_HANDLE 
ERROR_TOO_MANY_OPEN_FILES 


You can change the inheritance, fail-on-error, and write-through flags for the 
duplicate file handle by using the DosSetFHandState function. 


This example calls the DosDupHandle function to duplicate the standard output 
handle, and then writes “Hello World” to the new handle: 


HFILE hfNew; 

USHORT, cbBytesWritten; 

hfNew = OxFFFF; /* create new handle */ 
DosDupHandle(1, &hfNew) ; /* duplicate standard output */ 
DosWrite (hfNew, "Hello World\r\n", 13, &cbBytesWritten) ; 


DosChgFilePtr, DosClose, DosExecPgm, DosMakePipe, DosRead, DosSet- 
FHandState, Dos Write 


DosEnterCritSec 
VOID DosEnterCritSec( VOID) 


Return Value 
Comments 


See Also 


The DosEnterCritSec function suspends every thread in the current process, 
except for the calling thread. Suspended threads will not execute until the 
current thread calls the DosExitCritSec function. 


This function has no parameters. 
This function does not return a value. 


The signal handler (if installed) is not suspended when the DosEnterCritSec 
function is called. If a signal occurs, the processing done by the signal handler 
must not interfere with the processing done by the thread calling the DosEnter- 
CritSee function. 


DosCreateThread, DosExitCritSec, DosHoldSignal, DosSetSigHandler 


q 
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a DosErrClass 
USHORT DosErrClass(usErrorCode, pusCilass, pfsAction, pusLocus) 


USHORT usErrorCode; /» error value for analysis a/ 
PUSHORT pusC/ass; /» pointer to variable for error classification «/ 
PUSHORT pfsAction; /» pointer to variable for action »/ 
PUSHORT pusLocus; /» pointer to variable for error origin »/ 


The DosErrClass function retrieves a classification of an error value and a 
recommended action. 


The DosErrClass fuiiction is a family API function. 


Parameters usErrorCode Specifies the error value returned by an MS OS/2 function. 


pusClass Points to the variable that receives the classification of the error 
value. This parameter can be one of the following values: 


Value Meaning 


ERRCLASS_ALREADY Action already taken. 


ERRCLASS_APPERR An application error has probably occurred. 
ERRCLASS_AUTH Authorization has failed. 
ERRCLASS_BADFMT Bad format for call data. 
ERRCLASS_CANT Cannot perform requested action. 
ERRCLASS_HRDFAIL A device-hardware failure has occurred. 
ERRCLASS_INTRN An internal error has occurred. 
ERRCLASS_LOCKED Resource or data is locked. 
ERRCLASS_MEDIA Incorrect media; a CRC error has occurred. 
ERRCLASS_NOTEND | The item was not located. 
ERRCLASS_OUTRES Out of resources. 

ERRCLASS_SYSFAIL A system failure has occurred. 
ERRCLASS_TEMPSIT This is a temporary situation. 
ERRCLASS_TIME A time-out has occurred. 
ERRCLASS_UNK The error is unclassified. 


pfsAction Points to the variable that receives the recommended action for the 
specific error. This parameter can be one of the following values: 


Value Meaning 

ERRACT_ABORT Terminate in an orderly manner. 
ERRACT_DLYRET Delay and retry. 
ERRACT_IGNORE Ignore the error. 
ERRACT_INTRET Retry after user intervention. 
ERRACT_PANIC Terminate immediately. 
ERRACT_RETRY Retry immediately. 


ERRACT_USER Bad user input; get new values. 
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pusLocus Points to the variable that receives the error’s origin in the system. 
This parameter can be one of the following values: 


Value Meaning 
ERRLOC_DISK The error occurred in a random-access device, 
such as a disk drive. 

ERRLOC_MEM This is a memory-parameter error. 
ERRLOC_NET This is a network error. 
ERRLOC_SERDEV This is a serial-device error. 
ERRLOC_UNK The origin of the error is unknown. 

~ Return Value The return value is zero if the function is successful. Otherwise, it is an error 

value. 
Comments The ERRACT_, ERRCLASS_, and ERRLOC_ constants are defined in the 


bseerr.h file. 


Example This example calls the DosQFileMode function to determine the status of the file 
a:\abc.exe. If DosQFileMode returns an error, the DosErrClass function is 
called to determine the class of the error. The process terminates if the error is 
a device-hardware failure—for example, if a drive door is open or a specified 
disk drive is nonexistent. 

USHORT usAttribute, usError, usClass, fsAction, usLocus; 


usError = DosQFileMode("a:\\abc.ext", &usAttribute, OL); 
if (usError) { 


DosErrClass(usError, /* error number if 
&usClass, /* error classification a/ 
&fsAction, /* recommended action */ 
&usLocus) ; * error origin */ 
if (usClass == ERRCLASS_HRDFAIL) /* device-hardware failure */ 
DosExit(1, EXIT_PROCESS) ; /* exits application * 
See Also DosError, DosExit, DosQFileMode 


DosError 


USHORT DosError( fEnable) 
USHORT fEnablie; /« enable/disable error handling «/ 


The DosError function enables or disables hard-error and exception processing 
for a process. By default, the system displays a message and prompts for user 
input when a hard error or exception occurs. A hard error is typically an error 
that cannot be resolved by software—for example, when the drive door is 
opened while a removeable disk is being read. 


The DosError function disables the default processing by forgoing the displayed 
message and directing any function that encounters a hard error or exception to 
return an appropriate error value. The process must determine the appropriate 
action by referring to the error value. 


The DosError function is a family API function. 
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Parameters fEnable Specifies whether to disable or enable processing. This parameter can 
. be one of the following values: 

Value Meaning 
EXCEPTION_DISABLE Disable exception processing. 
EXCEPTION_ENABLE Enable exception processing. 
HARDERROR_DISABLE Disable hard-error processing. 
HARDERROR_ENABLE Enable hard-error processing. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 

value, which may be the following: 
ERROR_INVALID_DATA 
Comments By default, the system terminates any process in which an exception occurs. 


Although the DosError function can disable the message when an exception 
occurs, it cannot disable the termination of the process. To prevent a process 
from being terminated, use the DosSetVec function to trap the exception and 
carry out process-specific exception processing. 


Restrictions In real mode, the following restriction applies to the DosError function: 


™ If the fEnable parameter is HARDERROR_DISABLE, all subsequent 
int 24h requests fail until a call is made to the DosError function with 
fEnable set to HARDERROR_ENABLE. 


Example This example calls the DosError function to turn off hard-error processing, then 
calls the DosErrClass function to process any error that is received: 


USHORT usAttribute, usError, usClass, fsAction, usLocus; 
DosError (HARDERROR_DISABLE) ; /* turn off hard-error processing */ 
usError = DosQFileMode("a:\\abc.ext", G&usAttribute, OL); 
if (usError) { 
DosErrClass(usError, &usClass, &fsAction, &usLocus) ; 
if (usClass == ERRCLASS_HRDFAIL) 
DosExit(1, EXIT_PROCESS) ; 


See Also DosErrClass, DosSetF HandState 

DosExecPgm 

USHORT DosExecPgm(pchFaiiName, cbFailName, fExecFlags, pszArgs, pszEnv, prescResults, pszPgmName) 
PCHAR pchFailName; /« pointer to buffer for failed filename »/ 

SHORT cbFai/Name; /« size of failed filename buffer »/ 

USHORT fExecFiags; /« synchronous/trace flags »/ 

PSZ pszArgs; /» pointer to argument strings »/ 

PSZ pszEnv; /» pointer to environment strings »/ 

PRESULTCODES prescResuits; /» pointer to structure receiving result codes «/ 

PSZ pszPgmName; /« pointer to program name to execute »/ 


The DosExecPgm function loads and starts a child process. 
The DosExecPgm function is a family API function. 


Parameters 


DosExecPgm 


45 


pchFailName Points to the buffer that receives the name of the object (such 
as a dynamic-link module). The DosExecPgm function copies a name to this 
buffer if it cannot load and start the specified program. 


cbFailName Specifies the length (in bytes) of the buffer pointed to by the 


pchFailName parameter. 


fExecFlags Specifies how a given program should be run. This parameter can 


be one of the following values: 
Value 


EXEC_ASYNC 


EXEC_ASYNCRESULT 


EXEC_SYNC 


EXEC_BACKGROUND 


EXEC_TRACE 


Meaning 


Execute asynchronously to the parent process. 
The DosExecPgm function copies the process 
identifier of the child process to the code- 
Terminate field of the structure pointed to by 
the prescResults parameter. 


Execute asynchronously to the parent process. 
Before returning, the DosExecPgm function 
copies the process identifier of the child process 
to the codeTerminate field of the structure 
pointed to by the prescResults parameter. When 
the child process ends, the system saves the ter- 
mination and result codes in memory it reserves 
for these codes. This memory remains allocated 
until the parent process calls the DosCwait func- 
tion to retrieve the information. 


Execute synchronously to the parent process. 
When the child process ends, the DosExecPgm 
function copies its termination and result codes 
to the structure pointed to by the prescResults 
parameter. 


Execute asynchronously to the parent process 
and detach from the screen group of the parent 
process. The detached process executes in the 
background. If a process terminates the parent 
process—for example, by using the DosKill- 
Process function—the child process continues 
to run. The child process should not require 
screen output (other than through the 
VioPopUp function). The child process also 
should not call Vio, Kbd, or Mou functions. 


Execute under conditions for tracing. The 
parent process debugs the child process. 


program’s command parameters. The argument strings are copied to the 

process’s environment segment. The string can have any format but must end 
with two null characters. A typical format is the program name, a null character, 
the program parameters (separated. by spaces), and two null characters. 


If this parameter is zero, no argument strings are passed to the child process. 


-pszArgs Points to a set of null-terminated argument Strings that represent the 
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Return Value 


pszEnv Points to a set of nai seaniuated environment strings that represent 
environment variables and their current values. The environment strings are 
copied to the process’s environment segment. These strings represent environ- 
ment variables and their current values. An environment string has the following 
form: 


variable=value 


Two or more strings can be concatenated to pass multiple environment strings to 
the child process. The last environment string must end with two null characters. © 


If this parameter is zero, the child process inherits the unchanged environment 
of the parent process. 


prescResults Points to the RESULTCODES structure that receives the termi- 
nation and result codes of the child process. The RESULTCODES structure has 
the following form: 
typedef struct _RESULTCODES { 

SHORT codeTerminate; 


USHORT codeResult; 
} RESULTCODES; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pszPgmName Points to a null-terminated string that specifies the process to 
load and start. The string must be a valid MS OS/2 filename and include the 
filename extension. The string must specify an executable file. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED | 
ERROR_AUTODATASEG_EXCEEDS_64k 
ERROR_BAD_ENVIRONMENT 
ERROR_BAD_FORMAT 
ERROR_DRIVE_LOCKED 
ERROR_DYNLINK_FROM_INVALID_RING 
ERROR_EXE_MARKED_INVALID 
ERROR_FILE_NOT_FOUND 
ERROR_INTERRUPT 
ERROR_INVALID_DATA 
ERROR_INVALID_EXE_SIGNATURE 
ERROR_INVALID_FUNCTION 
ERROR_INVALID_MINALLOCSIZE 
ERROR_INVALID_MODULETYPE 
ERROR_INVALID_ORDINAL 
ERROR_INVALID_SEGDPL 
ERROR_INVALID_SEGMENT_NUMBER 
ERROR_INVALID_STACKSEG 
ERROR_INVALID_STARTING_CODESEG 
ERROR_ITERATED_DATA_EXCEEDS_64K 
ERROR_LOCK_VIOLATION 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_DOS_DISK 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_PATH_NOT_FOUND 
ERROR_PROC_NOT_FOUND 


Comments 


Restrictions 


Example 


See Also 
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ERROR_RELOC_CHAIN_XEEDS_SEGLIM 
ERROR_SHARING_BUFFER_EXCEEDED — 
ERROR_SHARING_VIOLATION 
ERROR_TOO_MANY_OPEN_FILES 


If the filename is a complete pathname (a drive name, path, and filename), the 
DosExecPgm function loads the program from the specified location. If only a 
filename is given and that filename is not found in the current directory, the 
DosExecPgm function searches each directory specified in the parent process’s 
PATH environment variable for the given file. 


The child process receives a discrete address space—that is, it receives its own 
local descriptor table. This means that the parent process and the child process 
cannot access each other’s data. To pass data between processes, the parent 
process typically opens a pipe by using the DosMakePipe function before start- 
ing the child process, then lets the child process access one end of the pipe. 


The environment segment of the child process consists of the environment 
strings (at offset zero), the program filename, and the argument strings. The 
system passes the offset to the argument strings in the bx register and the 
environment segment’s selector in the ax register. These values can also be 
retrieved by using the DosGetEnv function. 


When the child process starts, it inherits all pipe handles and all open file han- 
dles from the parent process. (File handles that are opened with the fsOpenMode 
parameter of the DosOpen function set to OPEN_FLAGS_NOINHERIT are 
not inherited by the child process—for more information, see the DosOpen 
function.) The child process can use these handles immediately, without opening 
or preparing them in any way. This gives the parent process control over the files 
associated with the standard input, output, and error file handles. For example, 
the parent process can redirect the standard output from the screen to a file by 
opening the file and duplicating its handle as the standard output handle 
(0x0001). If the child process then writes to the standard output, the data goes to 
the file, not to the screen. 


In real mode, the following restrictions apply to the DosExecPgm function: 


m The only value allowed for the fExecFlags parameter is EXEC_SYNC. 


™ The buffer pointed to by the pchFailName parameter is filled with 
blanks, even if the function fails. 


m@ The codeResult field of the RESULTCODES structure receives the exit 
code from either the DosExit function or the MS-DOS int 21h, 4cH sys- 
tem call, whichever is used to terminate the program. 


This example calls the DosExecPgm function to execute the program abc.exe. 
The program executes as a child process asynchronously with the parent pro- 
gram. 


CHAR achFailName [128] ; 
RESULTCODES rescResults; 


DosExecPgm(achFailName, /* object-name buffer */ 
sizeof (achFailName) , /* length of buffer +/ 
EXEC_ASYNCH, /* async flag */ 
“abe = 0\O", /* argument string */ 
oO, /* environment string */ 
&rescResults, /* address of result */ 
“abc.exe") ; /* name of program */ 


DosCreateThread, DosCwait, DosExit, DosGetEnv, DosKillProcess, DosOpen. 
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M DosExit 


VOID DosExit(fTerminate, usExitCode) 


USHORT fTerminate; 
USHORT usExitCode; 


Parameters 


Return Value 
Comments 


Restrictions 


Example 


See Also 


/« terminate current/all threads = «/ 
/« result code for parent process «/ 


The DosExit function ends a thread or a process and all its threads. 


_ The DosExit function is a family API function. 


fTerminate Specifies whether to terminate the current thread or the process 
and all its threads. If this parameter is EXIT.THREAD, only the current thread 
ends. If it is EXIT_.PROCESS, all threads in the process end. 


usExitCode Specifies the program’s exit code. 
This function does not return a value. 


If the fTerminate parameter is EXIT_.THREAD, the function ends the current 
thread. If the current thread is the last one in the process, the process also ends. 
If the fTerminate parameter is EXIT_PROCESS, the DosExit function termi- 
nates all threads in the process and creates a final temporary thread. The tem- 
porary thread executes any functions given in the list created by the DosExitList 
function. When this last thread ends, the system frees any resources used by the 
process. The exit code specified by the last call to the DosExit function is sup- 
plied to the parent process by using the DosCwait function. 


In real mode, the following restriction applies to the DosExit function: 


@ The function always exits from the current program, since there are no 
threads in the real-mode environment. 


This example creates a thread, referred to as thread 2. This example shows two 
ways of stopping thread 2: by stopping all threads in the process and by stopping 
thread 2 specifically. Thread 1, the main process, exits and ends all threads by 
calling the DosExit function with the first parameter set to EXIT.PROCESS. 
Thread 2, the thread created with the call to DosCreateThread, ends only itself, 
by calling DosExit with the first parameter set to EXIT_THREAD. 


BYTE bStackArea [2048]; 
main() { 


PVOID pStack2 = bStackArea + 512; 
TID tidThread2; 
DosCreateThread(Thread2, &tidThread2, pStack2) ; 


DosExit (EXIT_PROCESS, /* exit process */ 
0); /* return value */ 
+ 
VOID FAR Thread2() { 
DosExit (EXIT_THREAD, 7* exit thread, process continues */ 
0); . f* return value * 


¥ 
DosCwait, DosExecPgm, DosExitList 


M@ DosExitCritSec 
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VOID DosExitCritSec( VO/D) 


Return Value 
See Also 


@ DosExitList 


The DosExitCritSec function restores execution of all threads in the process that 
were suspended by the DosEnterCritSec function. 


This function has no parameters. 
This function does not return a value. 


DosCreateThread, DosEnterCritSec 


USHORT DosExitList ( fFn Code, pfnFunction) 


USHORT fFnCode; 


/« function code a/ 


PFNEXITLIST pfnFunction(USHORT); /« pointer to address of function »/ 


Parameters 


Return Value 


Comments 


The DosExitList function specifies a function that is executed when the current 
process ends. This “termination function” may define additional termination 
functions. The DosExitList function may be called one or more times: each call 
adds or subtracts a function from an internal list that is maintained by the sys- 
tem. When the current process terminates, MS OS/2 transfers control to each 
function on the list. 


fFnCode Specifies whether a function’s address is added to or removed from 
the list. This parameter can be one of the following values: 


Value Meaning 

EXLST_ADD Add function to termination list. 

EXLST_EXIT Termination processing complete; call the next func- 
tion on termination list. 

EXLST_REMOVE Remove function from termination list. 


pfnFunction Points to the termination function to be added to the list. For a 
full description, see the following “Comments” section. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_LINVALID_DATA 
ERROR_NOT_ENOUGH_MEMORY 


Dynamic-link-library modules often use the DosExitList function; this function 
allows library modules to free resources or clear flags and semaphores if the 
client process terminates without notifying them. 


The termination function has one parameter and no return value. The function 
should have the following form: 


PENEXITLIST FuncName (usTermCode) 
USHORT usTermCode; 
< 


DosExitList (EXLST_EXIT, 0); 
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Example 


See Also 


The usTermCode parameter of the termination function specifies the reason the 
process ended. This parameter is one of the following values: 


Value Meaning 

TC_EXIT Normal exit 
TC_HARDERROR _Hard-error abort 
TC_KILLPROCESS Unintercepted DosKillProcess 
TC_TRAP Trap operation 


Before transferring control to the termination function, MS OS/2 resets the 
stack to its initial value. MS OS/2 then passes control to the function by using a 
jmp instruction. The termination function should carry out its tasks and then 
call the DosExitList function with the fFnCode parameter set to EXLST_EXIT. 
This parameter setting directs the system to call the next function on the termi- 
nation list. When all functions on the list have been called, the process ends. 


Termination functions should be as short and fail-safe as possible. When the ter- 
mination functions are executed, all threads except for the one executing the 
DosExitList function have been destroyed. A termination function must call the 
DosExitList function to end; otherwise, the process “hangs,” since MS OS/2 
cannot terminate it. 


A termination function can call most MS OS/2 system functions; however, it 
must not call the DosCreateThread or DosExecPgm function. 


This example calls the DosExitList function, which then adds the locally defined 
function CleanUp to the list of routines to be called when the process termi- 
nates. The CleanUp function displays a message that it is cleaning up, then calls 
DosExitList, reporting that it has finished and that the next function on the ter- 
mination list can be called. 


DosExitList (EXLST_ADD, /* adds address to the list oy, 
CleanUp); /* function address 


DosExit (EXIT_PROCESS, 0); 
VOID PASCAL FAR CleanUp (usTermCode) 
USHORT usTermCode; 


ViowrtTTY ("Cleaning up...\r\n", 16, O); 


DosExitList (EXLST_EXIT, /* termination complete */ 
OL); 
N; 


_ DosCreateThread, DosExecPgm, DosExit 


@ DosFileLocks 
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USHORT DosFileLocks( hf, pfUniock, pflock) 


HFILE hf; 


/« file handle x/ 


PFILELOCK pfUnLock; /» pointer to range to be unlocked «/ 


PFILELOCK pfLock; 


Parameters 


Return Value 


Comments 


Example 


/« pointer to range to be locked —«/ 


The DosFileLocks function unlocks and/or locks a region in an open file. Lock- 
ing a region prevents other processes from accessing the locked region. 


The DosFileLocks function is a family API function. 


hf Identifies the file handle. This handle must have been created previously by 
using the DosOpen function. 


pfUnLock Points to the FILELOCK structure that specifies the starting posi- 
tion in the file and the number of bytes of the file to unlock. This parameter is 
ignored if NULL is specified instead of a structure address. The FILELOCK 
structure has the following form: . | 
typedef struct _FILELOCK { 

LONG 10ffset; 


LONG l1Range; 
} FILELOCK; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pfLock Points to the FILELOCK structure that specifies the starting position 
in the file and the number of bytes of the file to lock. This parameter is ignored 
if NULL is specified instead of a structure address. 


The return value is zero if the function is successful. Otherwise, it is an error. 
value, which may be one of the following: 


ERROR_INVALID_HANDLE 
ERROR_LOCK_VIOLATION 


The DosFileLocks function can both lock and unlock regions. The system 
unlocks any specified region before locking any other region. Locked regions can 
overlap, but if one region would entirely encompass another, the smaller region 
should be unlocked first. The DosFileLocks function can lock any part of a file. 
Attempting to lock bytes beyond the end of a file does not result in an error. 


This example opens the file abc and calls the DosFileLocks function to lock 100 
bytes of the file, starting with byte number three. No other file may read or write 
to this range in the file until DosFileLocks is called to unlock the range or the 
file is closed. The same structure is used to lock the file and to unlock the file. 
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See Also 


DosFindClose 


FILELOCK flock; 
HFILE hf; 
USHORT usAction; 


/* open the file */ 


DosOpen ("abc", /* filename to open * 
&hE, /* address of file handle */ 
&usAction, /* action taken */ 
100L, /* size of new file */ 
FILE_NORMAL, /* file attribute */ 
FILE_OPEN, /* open if file exists */ 
OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYNONE /* open mode ~ */ 
OL); /* reserved a/ 

flock.10ffset = 3L; /* offset to begin lock a/ 

flock.1Range = 100L; /* range to lock a/ 

DosFileLocks (hf, /* handle of file to lock */ 
NULL, /* unlock range (NULL to disable) */ 
&£lock) ; /* address of lock range */ 
. /* other file processing occurs here */ 

DosFileLocks (hf, /* handle of file to unlock */ 
&flock, /* address of unlock range */ 
NULL) ; /* lock range (NULL to disable) */ 


DosDupHandle, DosExecPgm, DosOpen 


USHORT DosFindClose ( hdir) 
HDIR hdir; = /« handle of search directory «/ 


Parameters 


Return Value 


Example 


See Also 


The DosFindClose function closes the specified search-directory handle. The 
DosFindFirst and DosFindNext functions use the search-directory handle to 
locate files with names that match a given name. 


The DosFindClose function is a family API function. 


hdir Identifies the search directory. This handle must have been previously 
opened by using the DosFindFirst function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_LINVALID_HANDLE 


This example calls the DosFindFirst function to find all files that match “*.*”. 
When DosFindFirst is finished, the handle is closed by calling the DosFindClose 
function. 


HDIR hdir = OxFEFFF; 

USHORT usSearchCount = 1; 

FILEFINDBUE findbuf; 

DosFindFirst("*.#", &hdir, FILE _NORMAL, &findbuf, 
sizeof(findbuf), &usSearchCount, OL); 


DosF indClose (hdir) ; /* closes the search directory */ 


DosFindFirst, DosFindNext, DosSearchPath 


H DosFindFirst 
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USHORT DosFindFirst(pszFileSpec, phdir, usAttribute, pfindbuf, usBufLen, pusSearchCount, ulReserved) 


PSZ pszFileSpec; /« pointer to string specifying pathname +/ 
PHDIR phdir; /« pointer to variable for handle »/ 
USHORT usAttribute; /« search attribute »/ 
PFILEFINDBUF pfindbuf; /« pointer to structure receiving result —«/ 
USHORT usBufLen; /« length of result buffer »/ 
PUSHORT pusSearchCount; /« pointer to variable for file count »/ 
ULONG u/Reserved; /x must be zero »/ 


Parameters 


The DosFindFirst function searches a directory for the file or files whose 
filename and attributes match the specified filename and attributes. The function 
copies the name and directory information of the file to the FILEFINDBUF 
structure. The information returned is as accurate as the most recent call to the 
DosClose or DosBufReset function. 


The DosFindFirst function is a family API function. 


pszFileSpec Points to a null-terminated string. This string must be a valid MS 
OS/2 pathname and may contain wildcard characters. 


phdir Points to the variable that contains the handle of the directory to be 
searched. 


If the phdir parameter is HDIR_SYSTEM, the system default search-directory 
handle is used. If it is HDIR_CREATE, the search directory that is used by the 
process is created, and the function copies the handle of this search directory to 
the variable pointed to by the phDir parameter. If the handle was created by a 
previous call to the DosFindFirst function, it can be used in subsequent calls to 
the DosFindNext function. 


usAttribute Specifies the file attribute(s) of the file to be located. This param- 
eter can be a combination of the following values: 


Value Meaning 
FILE_NORMAL Search for normal files. 
FILELREADONLY Search for read-only files. 
FILE_HIDDEN Search for hidden files. 
FILE_SYSTEM Search for system files. 
FILE_DIRECTORY . Search for subdirectories. 
FILE_LARCHIVED Search for archived files. 


pfindbuf Points to the FILEFINDBUF structure that receives the result of the 
search. The FILEFINDBUF structure has the following form: 


typedef struct _FILEFINDBUF { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
EDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FITIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 
UCHAR cchName; 
CHAR achName [13]; 

} FILEFINDBUE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


"Comments 


Restrictions 


usBufLen Specifies the length (in bytes) of the structure pointed to by the 
pfindbuf parameter. 


pusSearchCount Points to a variable that specifies the number of matching 
filenames to locate. The DosFindFirst function copies the number of filenames 
found to this parameter before returning. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_LINVALID_HANDLE 
ERROR_INVALID_PARAMETER 
ERROR_NO_MORE_FILES 
ERROR_NO_MORE_SEARCH_HANDLES 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 


The pusSearchCount parameter specifies the number of files to search for. The 
number of files whose information is copied is the number of files requested, the 
number of files whose information fits in the structure, or the number of files 
that exist, whichever is smallest. To receive information for more than one file, 
the pfindbuf parameter must point to a buffer that consists of consecutive FILE- 
FINDBUF structures—for example, an array of structures. If the DosFindFirst 
function fails to find a match or cannot copy all of the information about the file 
to the structure, it returns an error. 


The DosFindFirst function obtains a handle that can be used in subsequent calls 
to the DosFindNext function to specify the directory to search and the filename 
to search for. Each call to the DosFindFirst function automatically closes the 
handle of the search directory, if it has not been closed previously by using the 
DosFindClose function. 


Currently, the maximum filename length is 13 bytes: up to 8 characters in the 
filename; 4 characters, including the period (.), in the filename extension; and 
the terminating null character. The maximum filename length will change in 
future versions of MS OS/2. 


A search for read-only files, hidden files, system files, archived files, or sub- 
directories includes all normal files in addition to those matching the specified 
attribute. 


In real mode, the following restriction applies to the DosFindFirst function: 


@ The phdir parameter must be set to HDIR_SYSTEM. 


Example This example uses the DosFindFirst function to find the file abc.ext. An error 
message is displayed if the file is not found. 
HDIR hdir = HDIR_CREATE; 
USHORT usSearchCount = 1; 
FILEFINDBUF findbuf; 
if (DosFindFirst ("abc.ext", /* filename to search for 
&hdir, /* address of directory handle 
FILE_NORMAL, /* type of files to search for 
&findbuf, /* address of buffer 
sizeof(findbuf), /* size of buffer 
&usSearchCount, /* number of matching entries 
/* reserved 
VioWrtTTY("File not found\r\n", 16, 0); 
else { 
See Also DosBufReset, DosClose, DosFindClose, DosFindNext, DosQFileMode, 
DosQFSInfo 
DosFindNext 


DosFindNext 
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USHORT DosFindNext(hdir, pfindbuf, cbfindbuf, pusSearchCount) 


HDIR hdir; 

PFILEFINDBUF pfindbuf; 
USHORT cbfindbuf; 
PUSHORT pusSearchCount; 


/« handle of search directory 


/» length of result buffer 
/x pointer to variable for file count 


»/ 


/« pointer to structure receiving search result »/ 


»/ 
»/ 


The DosFindNext function searches for the next file or group of files matching 

the specified filename and attributes. The function copies the name and directory 
information of the file to the FILEFINDBUF structure pointed to by the pfindbuf 
parameter. The information returned is as accurate as the most recent call to the 


DosClose or DosBufReset function. 


The DosFindNext function is a family API function. 


Parameters hdir 


Identifies the search directory and the filename(s) to search for. This 
handle must have been created previously by using the DosFindFirst function. 


pfindbuf Points to the FILEFINDBUF structure that receives the result of the 
search. The FILEFINDBUF structure has the following form: 


typedef struct _FILEFINDBUF { 


FDATE fdateCreation; 
FITIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 

ULONG cbFileAlloc; 
USHORT attrFile; 

UCHAR cchName; 

CHAR achName [13]; 


} FILEFINDBUE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


Comments 


Restrictions 


Example 


See Also 


cbfindbuf Specifies the lenetn (in tiyiea) of the structure pointed to by the 
pfindbuf parameter. 


pusSearchCount Points to an unsigned variable that specifies the number of 
matching filenames to locate. The DosFindNext function copies the number of 
filenames found to the unsigned variable before returning. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_HANDLE 
ERROR_INVALID_PARAMETER 
ERROR_NO_MORE_FILES 
ERROR_NOT_DOS_DISK 


The pusSearchCount parameter specifies the number of files to search for. The 
number of files whose information is copied is the number of files requested, the 
number of files whose information fits in the structure, or the number of files 
that exist, whichever is smallest. If you want to receive information for more 
than one file, the pfindbuf parameter must point to a buffer that consists of con- 
secutive FILEFINDBUF structures—for example, an array of structures. If the 
DosFindNext function fails to find a match or cannot copy all of the information 
about the file to the structure, it returns an error. 


Currently, the maximum filename length is 13 bytes: up to 8 characters in the 
filename; 4 characters, including the period (.), in the filename extension; and 
the terminating null character. The maximum filename length will change in 
future versions of MS OS/2. 


In real mode, the following restriction applies to the DosFindNext function: 
@ The hdir parameter must be set to HDIR_SYSTEM. 


This example calls the DosFindFirst function to find all files matching “*.*”, and 
then uses the DosFindNext function to display them one at a time: 


HDIR hdir = OxFFFE; 

USHORT usSearchCount = 1; 

FILEFINDBUF findbuf; : 

DosFindFirst("*.*", &hdir, Ox00, &findbuf, sizeof (findbuf) , 
&usSearchCount, OL); 


do { 
ViowWrtITY(findbuf.achName, findbuf.cchName, O); 
VioWrtTTY("\r\n", 2, O); | /* cursor to next line */ 

- 

while (DosFindNext (hdir, /* handle of directory */ 
&findbuf, /* address of buffer */ 
sizeof (findbuf), /* length of buffer */ 
&usSearchCount) /* number of files to find */ 


== 0); /* while no error */ 


DosBufReset, DosClose, DosFindClose, DosFindFirst, DosQFileMode, 
DosQFSInfo 


DosFlagProcess 57 


— DosFlagProcess 
USHORT DosFlagProcess( pidProcess, fScope, usFlagNum, usFlagArg) 


PID pidProcess; /« identifier of process receiving flag +/ 
USHORT fScope; /« flag process or all processes »/ 
USHORT usFlagNum; /» flag number »/ 
USHORT usFlagArg; /« flag argument »/ 


The DosFlagProcess function generates a signal that is sent to the calling pro- 
cess. By default, the process ignores these signals, but it can respond to them by 
using the DosSetSigHandler function to define a signal handler. A process can 
also refuse event-flag signals, causing the DosFlagProcess function to return an 
error value. 


Parameters pidProcess Specifies the process identifier of the process that receives the 
flag. 
fScope Specifies how many external event flags to set. If this parameter is 
FLGP_SUBTREE, the function sets the external event flags for the specified 


process and all of its child processes. If it is FLGP_PID, the function sets the 
event flag for only the specified process. 


usFlagNum Specifies the number of the flag to set. This parameter can be 
one of the following values: 


Value Meaning 

PFLG_A Process flag A. 
PFLG_B Process flag B. 
PFLG_C Process flag C. 


usFlagArg Specifies an argument to pass to the specified process. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_FLAG_NUMBER 
ERROR_INVALID_FUNCTION 
ERROR_INVALID_PROCID 
ERROR_SIGNAL_REFUSED 


Comments The current signal cannot be accepted if a signal of the same type is already 
waiting to be processed. 


' Example This example executes a process called abc.exe. It then calls the DosFlag- 
Process function to send the PFLG_A (process flag A) signal to that process. 


CHAR achFailName [128]; 
RESULTCODES rescResults; 
DosExecPgm(achFailName, sizeof (achFailName) , 


EXEC_ASYNCH, “abc ", 0, G&rescResults, "abo. exe"); 


DosF lagProcess (rescResults.codeTerminate, /* process identifier */ 


FLGP_SUBTREE, /* notifies the entire subtree */ 
PFLG_ A, /* sends process flag A * 
1); /* value to send process */ 


See Also DosExecPgm, DosSetSigHandler 
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—M@ DosFreeModule 


USHORT DosFreeModule(hmod) 


HMODULE hmod; 


Parameters 


Return Value 


Comments 


See Also 


mM DosFreeSeg 


| module handle «/ 


The DosFreeModule function frees the specified dynamic-link module. After a 
process has freed a module, any function addresses the process may have 
retrieved from the module are no longer valid; a protection fault occurs if these 
functions are called. 


hmod Identifies the dynamic-link module to free. This handle must have been 
created previously by using the DosLoadModule function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_LINVALID_HANDLE 


If other processes have loaded the module and not yet freed it, the module 
remains in system memory for those processes. The system does not remove a 
module from memory until it is no longer used by any process. 


DosLoadModule 


USHORT DosFreeSeg(se/) 
SEL se/; /« segment selector «/ 


Parameters 


Return Value 


Restrictions . 


The DosFreeSeg function frees the specified memory segment. The function 
accepts selectors for memory segments, shared-memory segments, huge-memory 
segments, and aliased code segments. DosFreeSeg frees a shared-memory ‘seg- 
ment after the segment is freed by the last process accessing it. DosFreeSeg 
frees the code-segment selector for aliased code segments, but the corresponding 
data-segment selector remains valid until it is freed. 


The DosFreeSeg function is a family API function. 
sel Specifies the selector of the segment to free. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_ACCESS_DENIED 


In real mode, the following restriction applies to the DosFreeSeg function: 


m@ A code-segment selector (created by using the DosCreateCSAlias func- 
tion) and the corresponding data-segment selector are the same. Freeing 
one frees both. 
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Example This example allocates three segments of memory, then calls the DosFreeSeg 
function to free the memory: 


SEL sel; 
DosAllocHuge(3, 200, &sel, 5, SEG_NONSHARED) ; 


DosFreeSeg (sel) ; 


See Also DosAllocHuge, DosAllocSeg, DosAllocShrSeg, DosCreateCSAlias 
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USHORT DosFSRamSemClear{ pdosfsrs) 
PDOSFSRSEM podosfsrs; /« pointer to structure for semaphore «/ 


The DosFSRamSemClear function releases ownership of a fast-safe RAM sema- 


phore. 

Parameters pdosfsrs Points to the DOSFSRSEM structure containing the information 
about a fast-safe RAM semaphore. The DOSFSRSEM structure has the follow- 
ing form: 


typedef struct _DOSFSRSEM { 
USHORT cb; 
PID pid; 
TID tid; 
USHORT cUsage; 
USHORT client; 
ULONG sem; 
} DOSESRSEM; 


For more information, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments The DosFSRamSemClear function is used to release a semaphore obtained by 


using the DosFSRamSemRequest function. If the semaphore-use count for the 
current thread is zero, the semaphore is cleared and any threads that are 
blocked on the semaphore are restarted. 


DosFSRamSemClear cannot be issued against a fast-safe RAM semaphore that 
is owned by another thread. 


See Also DosFSRamSemRequest 


DosFSRamSemRequest 


USHORT DosFSRamSemRequest( pdosfsrs, /Timeout) 
PDOSFSRSEM pdosfsrs; /» pointer to structure for semaphore «/ 
LONG /Timeout; /« time to wait for semaphore «/ 


The DosFSRamSemRequest function obtains a fast-safe RAM semaphore and 
records the current owner for potential cleanup by a DosExitList function. 
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Parameters 


Return Value 


Comments 


pdosfsrs Points to the DOSFSRSEM structure containing information about a 
fast-safe RAM semaphore. The DOSFSRSEM structure has the following form: 


typedef struct _DOSFSRSEM { 


USHORT cb; 
PID pid; 
TID tid; 


USHORT cUsage; 
USHORT client; 
ULONG sem; 

} DOSEFSRSEM; 


For more information, see Chapter 4, “Types, Macros, Structures.” 


[Timeout Specifies how long to wait for the semaphore to become available. If 
the value is greater then zero, this parameter specifies the number of millisec- 
onds to wait before returning. If the value is SEM_IMMEDIATE_RETURN, 
the function returns immediately. If the value is SEM_INDEFINITE_WAIT, the 
function waits indefinitely. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


When the DosFSRamSemRequest function is called, it checks the status of the 
semaphore. If the semaphore is not owned, DosFSRamSemRequest sets it to 
owned, increases the use count, and returns immediately to the calling function. 
If the semaphore is owned, DosFSRamSemRequest may block the thread until 
the semaphore is not owned, then try again. The /Timeout parameter is used to 
place an upper limit on the amount of time to block before returning. 


When the thread is finished with the protected resource, it calls the DosFSRam- 
SemClear function. DosFSRamSemClear decreases the use count and, if the 
count is zero, sets the semaphore to unowned and starts any threads that were 
blocked while waiting for the semaphore. 


Recursive requests for fast-safe RAM semaphores are supported by a use count 
of the number of times the owning process has issued a DosFSRamSemRequest 
function without issuing a corresponding DosFSRamSemClear function. 


The DosFSRamSemRequest function does not return unless the specified sema- 


-phore remains clear long enough for the calling thread to obtain it. 


Fast-safe RAM semaphores operate by using the DOSFSRSEM structure. Before 
the initial call to the DosFSRamSemRequest function, this structure must be ini- 
tialized to zero and the cb field must be set to 14. The client field is provided to 
allow the calling process a means of identifying which resource is currently 
owned by the owner of the semaphore. This field is initialized to zero when a 
fast-safe RAM semaphore is first acquired. The owning process may use this 
field to describe the resource currently being accessed. The values in the client 
field may be useful to an DosExitList function handler in determining the 
appropriate cleanup action. 


When a process terminates that owns a fast-safe RAM semaphore, the Dos- 
ExitList functions of that process (if any) will be given control. If important 
resources are protected by fast-safe RAM semaphores, the DosExitList function 
should call the DosFSRamSemRequest function to gain ownership of these 
semaphores. When called during the processing of DosExitList termination func- 
tions, the DosFSRamSemRequest function will examine the indicated fast-safe 
RAM semaphore and, if it is owned by the active process, force the identifier of 
the owning thread to be equal to the identifier of the current thread and set the 


See Also 


DosGetCollate 
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use count to one. This allows the DosExitList function to be used without 
requiring any handling instructions for fast-safe RAM semaphores. When the 
execution of the DosExitList function is finished, it should call the DosFSRam- 
SemClear function. 


Except for the client field, the calling process should not modify any fields in the 
DOSFSRSEM structure after the DosFSRamSemRequest function returns. 


DosExitList, DosFSRamSemClear 


USHORT DosGetCollate (cbBuf, pctryc, pchBuf, pcbTable) 


USHORT cbBurf; 


/« size of buffer »/ 


PCOUNTRYCODE pcetryc; /» pointer to structure containing country code «/ 


PCHAR pchBuf; 
PUSHORT pcbTable; 


Parameters 


Return Value 


/« pointer to buffer for table »/ 
/x pointer to variable receiving table length »/ 


The DosGetCollate function retrieves the collating-sequence table for the given 
country code and code-page identifier. The collating-sequence table is a charac- 
ter array with 256 elements in which each element specifies the sorting weight of 
the corresponding character. (The sorting weight is the value used to determine 
if a character appears before or after another character in a sorted list.) Sorting 
weights and character values are not necessarily the same—for example, in a 
given character set, the sorting weights for the letters A and B might be 1 and 2, 
even though their character values are 65 and 66. 


The DosGetCollate function copies the collating-sequence table from the 
country.sys file to a buffer. If the buffer is too small to hold all the information, 
DosGetCollate truncates the information. If the buffer is larger than the infor- 
mation, DosGetCollate fills any remaining bytes with zeros. 


The DosGetCollate function is a family API function. 
cbBuf Specifies the size (in bytes) of the buffer that receives the collating- 
sequence table. 


pcetryc Points to the COUNTRYCODE structure that contains the country 
code and the code-page identifier used to retrieve the collating-sequence table. 
The COUNTRYCODE structure has the following form: 
typedef struct _COUNTRYCODE { 

USHORT country; 


USHORT codepage; 
} COUNTRYCODE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
pchBuf Points to the buffer that receives the collating-sequence table. 


pcbTable Points to the variable that receives the number of bytes copied to 
the buffer. 


- The return value is zero if the function is successful. Otherwise, it is an error 


value. 
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Comments The MS OS/2 sort command uses the DosGetCollate function to sort text 
according to the collating-sequence table. 


Restrictions In real mode, the following restriction applies to the DosGetCollate function: 


@ There is no method of identifying the boot drive. The system assumes 
that the country.sys file is in the root directory of the current drive. 


See Also DosCaseMap, DosGetCtryInfo 


DosGetCp 

USHORT DosGetCp(cbBuf, pusBuf, pcbCodePgLst) 

USHORT cbBuf; /« number of bytes in buffer for list »/ 
PUSHORT pusBuf; /x pointer to buffer receiving list «/ 


PUSHORT pcbCodePgLst; /» pointer to variable receiving list length »/ 


The DosGetCp function retrieves a list that contains the current code page for 
the process and all prepared system code pages. The code-page list consists of 
one or more 16-bit values, each value representing a code-page identifier. The 
first value in the list is the identifier for the process’s current code page. A pro- 
cess can set its current code page by using the DosSetCp function. Otherwise, 
the process inherits its current code page from its parent process. 


The DosGetCp function copies the code-page list to a buffer. If the buffer is too 
small to hold all the information, DosGetCp truncates the information. If the 
buffer is larger than the information, DosGetCp fills any remaining bytes with 
zeros. 


- Parameters cbBuf. Specifies the length (in bytes) of the buffer for the code-page list. 


pusBuf Points to the buffer that receives the code-page list. 


pcbCodePgLst Points to the variable that receives the number of bytes copied 
to the code-page list. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments The code-page identifier can be one of the following values: 
Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian 
865 Nordic 


See Also DosSetCp 


—™ DosGetCtryInfo 


DosGetCtryinfo 
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USHORT DosGetCtryInfo(cbBuf, pctryc, pctryi, pcbCountryinfo) 


USHORT cbBuf; /« length of data area »/ 
PCOUNTRYCODE pctryc; /« pointer to structure containing country info. +/ 
PCOUNTRYINFO pctry/: /« pointer to structure receiving country info. «/ 


PUSHORT pcbCountryinfo; /« pointer to variable for number of bytes »/ 


Parameters 


The DosGetCtryInfo function retrieves a copy of the country-dependent for- 
matting information for the specified country code and code-page identifier. 


Country-dependent formatting information defines the symbols and formats used 


to express currency values, dates, times, and numbers in a given country. 


The DosGetCtryInfo function copies the information from the country.sys file to 
the COUNTRYINFO structure. If this structure is too small to hold all the infor- 
mation, DosGetCtryInfo truncates the information. If the structure is larger than 


the information, the function fills any remaining bytes with zeros. 
The DosGetCtryInfo function is a family API function. _ 


cbBuf Specifies the size (in bytes) of the COUNTRYINFO structure. 


pcetryc Points to the COUNTRYCODE structure that contains the country 
code and the code-page identifier used to retrieve country-dependent informa- 
tion. The COUNTRYCODE structure has the following form: 


typedef struct _COUNTRYCODE { 
USHORT country; 
USHORT codepage; 

} COUNTRYCODE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pctryi Points to the COUNTRYINFO structure that receives the country- 
dependent formatting information. The COUNTRYINFO structure has the fol- 
lowing form: 


typedef struct _COUNTRYINEO { 
USHORT country; 
USHORT codepage; 
USHORT fsDateFmt ; 
CHAR szCurrency [5]; 
CHAR szThousandsSeparator [2] ; 
CHAR szDecimal [2]; 
CHAR szDateSeparator [2]; 

- CHAR szTimeSeparator [2]; 

UCHAR fsCurrencyFmt; 
UCHAR cDecimalPlace; 
UCHAR fsTimeFmt; 
USHORT abReservedi([2]; 
CHAR szDataSeparator [2]; 
USHORT abReserved2 [5]; 

} COUNTRYINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcbCountryInfo Points to the variable that receives the number of bytes of 
information copied to the COUNTRYINFO structure. 
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Return Value 


Restrictions 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NLS_BAD_TYPE | 
ERROR_NLS_NO_COUNTRY_FILE 
ERROR_NLS_NO_CTRY_CODE 
ERROR_NLS_OPEN_ FAILED 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_TYPE_NOT_FOUND 


In real mode, the following restriction applies to the DosGetCtryInfo function: 
™ There is no method of identifying the boot drive. The system assumes 
that the country.sys file is in the root directory of the current drive. 
DosGetDateTime 


USHORT DosGetDateTime ( pdateTime) 
PDATETIME pdateTime; / pointer to structure for date and time »/ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The DosGetDateTime function retrieves the current date and time. Although MS 
OS/2 maintains the current date and time, any process can change the date and 
time by using the DosSetDateTime function; as a result, the current date and 
time are as accurate as the most recent call to the DosSetDateTime function. 


The DosGetDateTime function is a family API function. 


pdateTime Points to the DATETIME structure that receives the date and time 
information. The DATETIME structure has the following form: 


typedef struct _DATETIME { 
UCHAR hours; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
UCHAR day; 
UCHAR month; 
USHORT year; 
SHORT timezone; 
UCHAR weekday; 

} DATETIME; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


A process can also retrieve the current date and time by using the DosGet- 
InfoSeg function. However, DosGetInfoSeg is available only to programs that 
run with MS OS/2. 


This example calls the DosGetDateTime function repeatedly until the time 
is 9:30: 

DATETIME date; 

do /* do until 9:30 */ 


DosGetDateTime (&date) ; 
while (!(date.hours == 9 && date.minutes == 30)) 


DosGetInfoSeg, DosSetDateTime 
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HM DosGetDBCSEv 


USHORT DosGetDBCSEv( cbBuf, pctryc, pchBuf) 


USHORT cbBuf; 


/« length of buffer »/ 


PCOUNTRYCODE pctrye; /» pointer to structure for country code «/ 


PCHAR pchBuf; 


Parameters 


Return Value 


Comments 


/« pointer to buffer for DBCS information «/ 


The DosGetDBCSEv function retrieves the double-byte character set (DBCS) 
environment vector for the given country code and code-page identifier. 


The DosGetDBCSEy function is a family API function. 


cbBuf Specifies the size (in bytes) of the buffer that receives the DBCS 
environment vector. 


pcetryc Points to the COUNTRYCODE structure that contains the country 
code and code-page identifier used to retrieve the DBCS environment vector. 
The COUNTRYCODE structure has the following form: 


typedef struct _COUNTRYCODE { 
USHORT country; 
USHORT codepage; 

} COUNTRYCODE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pchBuf Points to the buffer that receives the country-dependent DBCS 
environment vector. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NLS_BAD_TYPE 
ERROR_NLS_NO_COUNTRY_FILE 
ERROR_NLS_NO_CTRY_CODE 
ERROR_NLS_OPEN_FAILED 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_TYPE_NOT_FOUND 


The DBCS environment vector defines the first and last values in the ranges for 
the DBCS lead-byte and second-byte values. 


The DosGetDBCSEv function copies the information from the country.sys file to 
a buffer. The first two bytes in the environment vector specify the first and last 
values in the range for the DBCS lead-byte values. All subsequent pairs of bytes 
(except for the last two bytes) specify the first and last values in the ranges for 
DBCS second-byte values. The last two bytes are both set to zero. The form of 
the information is similar to the following: 


CHAR first1, lastl1; 
CHAR first2, last2; 


CHAR firstn, lastn; 
CHAR firstend=0, lastend=0; 
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Restrictions 


See Also 


DosGetEnv 


If the buffer is too small to hold all of the information, the DosGetDBCSEv 
function truncates the information. To avoid this, make sure the buffer is at least 
ten bytes long. You can verify that all information has been copied by checking 
the last two bytes to make sure they are zeros. If the structure is larger than the 
information, the function fills any remaining bytes with zeros. 


In real mode, the following restriction applies to the DosGetDBCSEv function: 


m There is no method of identifying the boot drive. The system assumes . 
that the country.sys file is in the root directory of the current drive. 


DosCaseMap, DosGetCollate, DosGetCp, DosGetCtryInfo, DosSetCp, 
VioGetCp, VioSetCp 


USHORT DosGetEnv({ pse/Environ, pusOffsetCmd) 
PUSHORT psel/Environ; /« pointer to variable for selector »/ 
PUSHORT pusOffsetCma; /« pointer to variable for offset —«/ 


Parameters 


Return Value 


Comments 


The DosGetEnv function retrieves the address of the process’s environment and 
an offset into the environment where the command line is stored that was used 
to start the process. This offset can be used to retrieve command-line arguments. 


The environment is one or more null-terminated strings that name and define the 
environment variables available to the current process. The command-line string 
is a single null-terminated string that is a copy of the command line that was 
used to run the process. 


The DosGetEnv function is a family API function. 
pselEnviron Points to the variable that receives the environment’s segment 


selector. The environment begins in the first byte of the seemient a identified by 
this parameter. 


pusOffsetCmd Points to the variable that receives the offset from the begin- 
ning of the specified segment to the beginning of the command line. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_ACCESS 


Each string in the environment has the following form: 
stringname=value 


Each environment string ends with a null character. The last string is followed 
by an additional null character to indicate the end of the environment. The two 
null characters are followed by the command-line string. 
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The DosGetEnv function is typically used to retrieve the command-line argu- 
ments. Although DosGetEny can be used to retrieve a single environment vari- 
able, an easier way to do this is to call the DosScanEnv function. 


Example This example calls the DosGetEnv function to retrieve the selector to the 
environment and the offset to the argument table within the environment. The 
pszEnviron parameter points to the beginning of the environment, and the 
pszArgument parameter points to the beginning of the argument table. 

PSZ pszEnviron, pszArgument; 

SEL selEnviron; 

USHORT usOffsetCmd; 

DosGetEnv (&selEnviron, &usOffsetCmd) ; 


pszEnviron = MAKEP(selEnviron, 0); 
pszArgument = MAKEP(selEnviron, usOffsetCmd) ; 


See Also DosExecPgm, DosScanEny 


DosGetHugeShift 


USHORT DosGetHugeShift ( pusShiftCount) 
PUSHORT pusShiftCount; /« pointer to variable receiving shift count «/ 


The DosGetHugeShift function retrieves the shift count used to compute the 
segment-selector offset for huge memory segments. (Huge memory segments are 
allocated by using the DosAllocHuge function.) The shift count represents a 
multiple of two, so the segment-selector offset is equal to the value 1 shifted left 
by the shift count. For example, the segment-selector offset is eight if the shift 
count is three. 


The DosGetHugeShift function is a family API function. 


Parameters pusShiftCount Points to the variable that receives the shift count. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

See Also DosAllocHuge 

DosGetinfoSeg 


USHORT DosGetinfoSeg( pselGlobalSeg, pselLocalSeg) 
PSEL pse/GlobalSeg; /« pointer to variable for global selector »/ 
PSEL pse/Loca/Seg; /» pointer to variable for local selector  «/ 


The DosGetInfoSeg function retrieves segment selectors for the global and local 
information segments. These read-only information segments contain general 
information about the system and the process. The global information segment is 
accessible only to all processes. The local information segment is accessible only 
to the current process. 
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Parameters pselGlobalSeg Points to the GINFOSEG structure that contains global infor- 
mation. The GINFOSEG structure has the following form: 


typedef struct _GINFOSEG { 
ULONG time; 
ULONG msecs; 
UCHAR hour; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
USHORT timezone; 
USHORT cusecTimerInterval; 
UCHAR day; . 
UCHAR month; 
USHORT year; 
UCHAR weekday; 
UCHAR uchMajorVersion; 
UCHAR uchMinorVersion; 
UCHAR chRevisionLetter; 
UCHAR sgCurrent; 
UCHAR sgMax; 
UCHAR cHugeShift; 
UCHAR fProtectModeOnly; 
USHORT pidForeground; 
UCHAR fDynamicSched; 
UCHAR csecMaxWait; 
USHORT cmsecMinSlice; 
USHORT cmsecMaxSlice; 
USHORT bootdrive; 
UCHAR amecRAS [32]; 
UCHAR csgwindowableVioMax; 
UCHAR csgPMMax; 

} GINFOSEG; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pselLocalSeg Points to the LINFOSEG structure that contains local informa- 
tion. The LINFOSEG structure has the following form: 


typedef struct _LINFOSEG { 


PID pidCurrent; 
PID pidParent; 

USHORT prtyCurrent; 
TID tidCurrent; 


USHORT sgCurrent; 
UCHAR rfProcStatus; 
UCHAR dummy 1 ; 
BOOL fForeground; 
UCHAR typeProcess; 
UCHAR dummy 2 ; 
SEL selEnvironment; 
USHORT offCmdLine; 
USHORT cbDataSegment; 
USHORT cbStack; ; 
USHORT cbHeap; 
HMODULE hmod; 
SEL selDS; 

} LINFOSEG; : 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value 


Example 


See Also 
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The return value is zero if the function is successful. Otherwise, it is an error 
value. 


This example calls the DosGetInfoSeg function to retrieve the selector of a sys- 
tem global segment, converts the segment selector into a pointer to a structure, 
and checks to determine if the current day of the week is Monday: 

SEL selGlobalSeg, selLocalSeg; 

GINFOSEG FAR *pgis; 

DosGetInfoSeg(&selGlobalSeg, &selLocalSeg) ; 


pgis = MAKEPGINFOSEG(selGlobalSeg) ; 
if (pgis->weekday == 1) { 


. /* this code is executed only on a Monday */ 


DosGetDateTime 


DosGetMachineMode 


USHORT DosGetMachineMode( pbMachineMode) 
PBYTE pbMachineMode; /« pointer to variable for machine mode «/ 


Parameters 


Return Value 


Example 


The DosGetMachineMode function retrieves the current machine mode—that is, 
whether the current mode is real or protected. 


The DosGetMachineMode function is a family API function. 


pbMachineMode Points to the variable that receives the machine mode. If 
this parameter is MODE_REAL, the current mode is real mode, 808% or 80x86. — 
If this parameter is MODE_PROTECTED, the current mode is protected mode, 
80x86. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The DosGetMachineMode function allows a program that is running in real 
mode to avoid calling functions that are not available when it is in real mode. 
The MS OS/2 functions that are available in both real and protected modes are 
listed in the Microsoft Operating System/2 Programmer’s Reference, Volume 1. 


This example calls the DosGetMachineMode function and displays the machine 
mode under which the current process is running: 


BYTE bMode; 
DosGetMachineMode (&bMode) ; 
if (bMode == MODE_PROTECTED) 
VioWrtTTY ("Protected mode\r\n", 16, 0); 
else 
VioWrtTTY("Real mode\r\n", 11, 0); 
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™ DosGetM essage 


USHORT DosGetMessage(ppchVTable, usVCount, pchBuf, cbBuf, usMsgNo, pszFileName, pcbMsg) 
PCHAR FAR * ppchVTable; /»« pointer to table of pointers to strings «/ 


USHORT usVCount; 
PCHAR pchButf; 
USHORT cbBuf; 
USHORT usMsgNo; 
PSZ pszFileName; 
PUSHORT pcbMsg; 


Parameters 


Return Value 


/« number of pointers in table »/ 
/x pointer to buffer receiving message «/ 
/« number of bytes in buffer x/ 
/« message number to retrieve »/ 
/« name of file containing message »/ 


/x number of bytes in returned message «/ 


The DosGetMessage function retrieves a message from the specified system- 
message file. DosGetMessage may insert one or more strings into the body of 
the message as it retrieves the message. 


The DosGetMessage function is a family API function. 


ppchVTable Points to a table of pointers to substitution strings. Each entry in 
the table points to a null-terminated string to be inserted into the message. Up to 
nine pointers can be given. 


usVCount Specifies the number of pointers in the table. This parameter can 
be any value from 0 through 9. If this parameter is zero, the ppchVTable parame- 
ter is ignored. If it is greater than 9, the DosGetMessage function returns an 
error indicating that the usVCount parameter is out of range. 


pchBuf Points to the buffer that receives the requested message. 
cbBuf Specifies the length (in bytes) of the buffer. 
usMsgNo_ Specifies the message number for the requested message. 


pszFileName Points to a null-terminated string that specifies the MS OS/2 
path and filename of the message file that contains the message. 


pcbMsg . Points to the variable that receives the number of bytes copied to the 
buffer. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_FILE_LNOT_FOUND 
ERROR_MR_INV_IVCOUNT 
ERROR_MR_INV_MSGF_FORMAT 
ERROR_MR_MID_NOT_FOUND 
ERROR_MR_MSG_TOO_LONG 
ERROR_MR_UN_ACC_MSGF 
ERROR_MR_UN_PERFORM 


Comments 


Restrictions 


See Also 


DosGetMessage /71 


To retrieve the requested message, the DosGetMessage function first searches 
the process’s message segment, if there is one. If it cannot find the specified 
message, the function then searches the specified message file. If no drive or 
path is specified in the filename, DosGetMessage searches the system root direc- 
tory for the message file, then searches the current directory on the current 
drive. The DosGetMessage function may also search the directories specified by 
the commands append (in real mode) and dpath (in protected mode) for the 
given message file. 


When the DosGetMessage function finds a message, it copies the message to the 
buffer pointed to by the pchBuf parameter. As it copies the message, DosGet- 
Message replaces any symbol in the form %x (where x is a digit from 1 through 
9) with one of the strings pointed to in the table pointed to by the ppchVTable 
parameter. For example, DosGetMessage replaces all symbols in the form %1 
with the string pointed to by the first pointer in the table. If there is no 
corresponding string in the table, DosGetMessage copies the %x symbol, 
unchanged, to the buffer. : 


The %x symbols used in a message are not necessarily enclosed in spaces. If you 
want spaces, you may need to supply them as part of your substitution strings. 


If the message is too long to fit in the buffer, the DosGetMessage function trun- 
cates the message and returns an error code. 


If the DosGetMessage function cannot retrieve a message because of a direct- 
access-storage-device (DASD) hard error or because it cannot find the message 
file, it places a default message in the buffer. This can occur when an invalid - 
parameter is specified—for example, an invalid usMsgNo parameter or an invalid 
usVCount parameter; when the DosGetMessage function cannot read the 
system-message file—for example, when a DASD error occurs or when format 
of the message file is invalid; or when the DosGetMessage function cannot find 
the system-message file. The DosGetMessage function retrieves messages that 
have been prepared previously by using the mkmsgf utility to create a message 
file. DosGetMessage also retrieves messages that have been added to the mes- 
sage segment of the program’s executable file by using the msgbind utility. It is 
irrelevant to the process that calls the DosGetMessage function whether Dos- 
GetMessage retrieves messages from the message segment or from the message 
file. In either case, the function uses the usMsgNo and pszFileName parameters 
to locate the message. For more information on the mkmsgf and msgbind utili- 
ties, see Microsoft Operating System/2 Programming Tools. 


In real mode, the following restriction applies to the DosGetMessage function: 


™ There is no method of identifying the boot drive. 


DosInsMessage, DosPutMessage 
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HH DosGetModHandle 
USHORT DosGetModHandle (pszModName, phMod) 


PSZ pszModName; 
PHMODULE phMod; 


Parameters 


Return Value 


Comments 


See Also 


/x module name »/ 
/« pointer to variable receiving module handle «/ 


The DosGetModHandle function retrieves the handle of a dynamic-link module. 
The DosGetModHandle function is typically used to make sure that a module 
has been loaded into memory. If the module has not been loaded, the function 
returns an error value. 


pszModName Points to a null-terminated string that specifies the MS OS/2 
filename of the module. The .dil filename extension is used for dynamic-link 
libraries. 


phMod Points to the variable that receives the module handle. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_MOD_NOT_FOUND 


The module name specified by the pszModName parameter must match the 
name of the module that is already loaded. Otherwise, an error value is 
returned. 


DosFreeModule, DosGetModName, DosLoadModule 


| DosGetModName 
USHORT DosGetModName(hmod, cbBuf, pchBuf) 


HMODULE hmod; 
USHORT cbBuf; 
PCHAR pchBuf; 


Parameters 


Return Value 


/« module handle «/ 
/x number of bytes in buffer s/ 
/« pointer to buffer receiving module name «/ 


The DosGetModName function retrieves the drive, path, and filename of the 
specified module. 


hmod Identifies the dynamic-link module. This handle must have been created 
previously by using the DosLoadModule function. 


cbBuf Specifies the maximum length (in bytes) of the buffer that receives the 
the information about the module: 


pchBuf Points to the buffer that receives the module’s drive, path, and 
filename. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_LENGTH 
ERROR_INTERRUPT 
ERROR_LINVALID_HANDLE 
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Comments The DosGetModName function returns an error if there is not enough room in 
the buffer for the drive, path, and filename. 


When a function within a dynamic-link library is called, or when the dynamic- 
link library initializes itself, the di register contains the module handle for the 
current process. 


See Also DosFreeModule, DosGetModHandle, DosLoadModule, DosMonOpen 


DosGetPID 


USHORT DosGetPID( ppidi) 
PPIDINFO ppidi; /« pointer to structure receiving identifiers »/ 


The DosGetPID function retrieves the process, thread, and parent-process 
identifiers for the current process. 


Parameters ppidi Points to the PIDINFO structure that receives the process identifiers. 
The PIDINFO structure has the following form: 


typedef struct _PIDINFO { 
PID pid; 
TID tid; 
PID pidParent; 
' } PIDINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is zero if the function is successful. Otherwise, it is an error. 
value. 

See Also DosExecPgm, DosGetPPID 

DosGetPPID 

USHORT DosGetPPID( pidChild, ppidParent) 

USHORT pidChild; /« process identifier of child process »/ 


PUSHORT ppidParent; /« point to variable for parent-process identifier «/ 
The DosGetPPID function retrieves the process identifier of a parent process. 


Parameters pidChild Specifies the process identifier of the child process. 


ppidParent Points to the variable that receives the process identifier of the 
parent process. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_PROCID 
See Also DosGetPID 


74. DosGetProcAddr 


HZ DosGetProcAddr 


USHORT DosGetProcAddr(hmod, pszProcName, ppfnProcAddress) 


HMODULE hmog; 
PSZ pszProcName; 


/« handle of module a/ 
/« pointer to module-name string af 


PPFN ppfnProcAdaress; /« pointer to variable for procedure address «/ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The DosGetProcAddr function retrieves the address of a procedure in a 
specified dynamic-link module. This address can then be used to call the ie 
cedure. 


hmod Identifies the dynamic-link module. This handle must have been created 
previously by using the DosLoadModule function. 


pszProcName Points to a null-terminated string that specifies the procedure 

name to retrieve. If this string starts with a number sign (#), the remaining part 
of the string is treated as an ASCII ordinal. Alternately, if the selector portion 
of the pointer is zero, the offset portion of the pointer is an explicit entry num- 
ber (an ordinal) within the dynamic-link module. 


ppfnProcAddress Points to the variable that receives the procedure address. 


- The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_INVALID_HANDLE 
ERROR_PROC_NOT_F OUND 


Although the DosGetProcAddr function can be used to retrieve procedure 
addresses from the DOSCALLS dynamic-link module, these procedures are 
available through ordinal values only. If you attempt to retrieve a procedure 
address from the DOSCALLS module by using a procedure name, DosGet- 
ProcAddr returns an error. 


This example calls the DosLoadModule function to load the dynamic-link 
module ghdil.dil. It then calls the DosGetProcAddr function to retrieve the 
address of the BOXMESSAGE function that is defined in the module and calls 
the DosFreeModule function to free the dynamic-link module. (This example is 
accurate if ghdil.dll exists in a directory defined by the libpath parameter of the 
config.sys file, and if ghdil.dil contains the BOXMESSAGE function that uses 
the Pascal calling convention.) 


CHAR achFailName [128]; 
HMODULE hmod; 
VOID (PASCAL FAR *pfnBoxMsg) (PSZ, BYTE, BYTE, SHANDLE, SHANDLE, BOOL); 


DosLoadModule(achFailName, sizeof(achFailName), “qhdll", &hmod); 

DosGetProcAddr (hmod, /* module handle’ * 
"BOXMESSAGE", /* name of function * 
&pfnBoxMsg) ; /* variable for function address */ 

pfnBoxMsg("Hello World", Ox30, 1, 0, 0); 

DosFreeModule (hmod@) ; 


DosFreeModule, DosGetModName, DosLoadModule 
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a DosGetPrty 
USHORT DosGetPrty(usScope, pusPriority, pid) - 


USHORT usScope; /« thread priority in current process/another process «/ 
PUSHORT pusPriority; /« pointer to variable for priority »/ 
USHORT pid; /» process or thread identifier »/ 


The DosGetPrty function retrieves the scheduling priority of a specified thread 
in the current process or the priority of thread 1 in a specified process. 


Parameters usScope Specifies whether to retrieve the priority for a thread in the current 
process or the priority of thread 1 in some other process. 


If the usScope parameter is PRTYS_PROCESS, the DosGetPrty function 
retrieves the priority of thread 1 for the process specified by the pid parameter. 
If thread 1 for that process has terminated, the DosGetPrty function returns an 
error value. 


If the usScope sarametee is PRTYS_THREAD, the function retrieves the prior- 
ity of the thread specified by the pid parameter. 


pusPriority Points to the variable that receives the scheduling priority of the 
specified thread. The high-order byte is set to the priority class; the low-order 
byte is set to the priority level. 


pid Specifies a process or thread identifier, depending on the value of the 
usScope parameter. If the pid parameter is 0x0000, the DosGetPrty function 
retrieves the priority for the current process or thread. 


Return Value | The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PROCID 
ERROR_INVALID_SCOPE 
ERROR_INVALID_THREADID 


See Also DosSetPrty 


a DosGetResource 
USHORT DosGetResource(hmod, jd Type, idName, pse!) 


HMODULE hmog; /« module handle »/ 
USHORT idType; /« resource-type identifier a/ 
USHORT idName; _/« resource-name identifier a/ 
PSEL pse/; /x pointer to variable for resource selector «/ 


The DosGetResource function retrieves the specified resource from a specified 
executable file. The function allocates a segment, copies the resource into the 
segment, and returns the segment selector. A process can use this segment 
selector to access the resource directly. : 


Parameters hmod Identifies the module that contains the resource. This parameter can be 
either the module handle returned by the DosLoadModule function or NULL 
for the application’s module. 
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idType Specifies the type of resource to retrieve. 
idName_ Specifies the name of the resource to retrieve. 


psel Points to the variable that receives the selector of the segment containing 


the resource. 


Return Value 


The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be one of the following: 


ERROR_CANT_FIND_RESOURCE 
ERROR_LINVALID_MODULE 
ERROR_LINVALID_SELECTOR 


Comments The following list describes the predefined types that can be used for the idType 
parameter: 

Type Meaning 
RT_ACCELTABLE Accelerator tables 
RT_BITMAP Bitmap 
RT_CHARTBL Glyph to character tables 
RT_DIALOG Dialog template 
RT_DISPLAYINFO Screen-display information 
RT_FONT Font 
RT_FONTDIR Font directory 
RT_KEYTBL Key to UGL tables 
RT_MENU ‘Menu template 
RT_MESSAGE Error-message tables 
RT_POINTER Mouse-pointer shape 
RT_RCDATA Binary data 
‘RT_STRING String tables 
RT_VKEYTBL Key to virtual-key tables 

See Also DosLoadModule 

DosGetSeg 

USHORT DosGetSeg(se/) 

SEL sei; /» selector of shared memory segment «/ 


The DosGetSeg function obtains access to the shared memory segment identified | 
by a specified segment selector. Although a process can receive the selector for 
a shared memory segment from another process, it cannot use the selector to 
access the segment until it uses the DosGetSeg function. 


Parameters sel Specifies the selector for the shared memory segment. 


Return Value 
value. 


The return value is zero if the function is successful. Otherwise, it is an error 
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Comments DosGetSeg obtains access only to shared memory segments created by using the 
DosAllocSeg function with the fAlloc parameter set to SEG_GETTABLE. 

See Also DosAllocSeg, DosGetShrSeg, DosGiveSeg 

DosGetShrSeg 


USHORT DosGetShrSeg(pszName, pse/) 
PSZ pszName; /« pointer to memory-segment name «/ 
PSEL psel; /« pointer to variable for selector —«/ 


The DosGetShrSeg function retrieves a selector to a shared memory segment. 
The shared segment must have been allocated previously by another process. 
The function increases the segment’s reference count by one to indicate that the 
segment is in use. The process receiving the new selector may use it to obtain 
access to the shared memory segment. 


Parameters pszName Points to a null-terminated string that identifies the shared memory 
segment. This string must have the following form: 
\sharemem\pszName 


The string name, pszName, must have the same format as an MS OS/2 filename 
and must be unique. 


psel_ Points to the variable that receives the new selector for the shared mem- 
ory segment. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 
ERROR_FILE_NOT_FOUND 
ERROR_INVALID_HANDLE 
ERROR_TOO_MANY_OPEN_FILES 
See Also DosAllocShrSeg, DosFreeSeg, DosGetSeg 
DosGetVersion 
USHORT DosGetVersion( pusVersion) 
PUSHORT pusVersion; /« pointer to variable receiving version number «/ 


The DosGetVersion function retrieves the operating system’s version number. 
For MS OS/2, version 1.1, both the major and minor version numbers are 10. 


The DosGetVersion function is a family API function. 
Parameters pusVersion Points to the variable that receives the version number. The high- 


order byte is set to the major version number; the low-order byte is set to the 
minor version number. 
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Return Value 


Example 


See Also 


DosGiveSeg 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


This example retrieves the ' version number and displays the major version num- 
ber: 


USHORT usVersion; 
CHAR ch; 


DosGetVersion (&usVersion) ; 

ch = (LOBYTE(usVersion) / 10) + 'O'; /* gets major version number */ 
VioWrtTTY ("You are using MS OS/2 version ", 30, 0); 

VioWrtTTY (&ch, 1, 0); 

VioWrtTTY("\r\n", 2, O); 


DosQSysInfo 


USHORT DosGiveSeg(sel/, pidProcess, pse/Recipient) 


SEL sel; 
PID pidProcess;: 


PSEL pse/Recipient; 


Parameters 


Return Value 


Comments 


See Also 


/« selector of shared memory segment s/ 
/« process identifier of recipient »/ 
/ pointer to variable for selector of recipient «/ 


The DosGiveSeg function creates a new segment selector for a shared memory 
segment. The new selector can then be used by another process to access the 
shared memory segment. 


The process that creates the new segment selector is responsible for passing the 
selector to any process that uses the segment. 


sel Specifies the segment selector of the shared memory segment. 


pidProcess Specifies the process identifier of the process that receives access 
to the shared memory segment. 


pselRecipient Points to the variable that r receives the new segment selector. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_NOT_ENOUGH_MEMORY 


The DosGiveSeg function is successful even if the specified process already has 
access to the segment. 


DosGiveSeg applies only to shared memory segments created by using the 
DosAllocSeg function with the fAlloc parameter set to SEG_GIVEABLE. 


DosAllocSeg, DosGetSeg 


—@ DosHoldSignal 
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USHORT DosHoldSignal ( fDisable) 


USHORT fDisable; 


Parameters 


Return Value 


Comments 


Restrictions 


Example 


See Also 


/« disable/enable signals «/ 


The DosHoldSignal function disables or enables signal processing for the current 
process. 


The DosHoldSignal function is a family API function. 


fDisable Specifies whether to disable or enable signals that are intended for 
the current process. If this parameter is HLDSIG_DISABLE, the function dis- 
ables signals. If it is HLDSIG_ENABLE, the function enables signals and 
restores the request count to its value before the last call to DosHoldSignal. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_LINVALID_FUNCTION 


If the fDisable parameter is HLDSIG_DISABLE, the function holds all signals 
without processing them until DosHoldSignal is called again with fDisable set to 
HLDSIG_ENABLE. Signals should be held for as little time as possible; if 
necessary, a signal should be released and then held again. 


Requests to disable and enable signal processing are cumulative. This means two 
requests to disable processing must be followed by two requests to enable pro- 
cessing before processing is enabled. 


The DosHoldSignal function is intended to be used by library routines, subsys- 
tems, and similar code that need to prevent a possible signal from interfering 
with the completion of the current activity—for instance, activity in locked seg- 
ments or in temporarily reserved resources. 


In real mode, the following restriction applies to the DosHoldSignal function: 


@ Only the signal interrupt (SIG_CTRLC) and signal break 
(SIG_CTRLBREAK) signals are recognized. 


This example calls the DosHoldSignal function to disable signals and calls the 
DosEnterCritSec function to stop all other threads. When the processing of the 
critical section of code is completed, the DosHoldSignal function enables signals 
again: 


DosHoldSignal (HLDSIG_DISABLE) ; /* disables signals a/ 
DosEnterCritSec() ; /* enters critical section */ 
DosExitCritSec() ; /* exits critical section */ 
DosHoldSignal (HLDSIG_ENABLE) ; /* enables signals * 


DosCLlAccess, DosEnterCritSec, DosFlagProcess 
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™ DosInsMessage 


USHORT DosinsMessage(ppchVTable, usVCount, pszMsg, cbMsg, pchBuf, cbBuf, pcbMsg) 
PCHAR FAR * ppchVTabie; /x pointer to table of character pointers »/ 


USHORT usVCount; 
PSZ pszMsqg; 
USHORT cbMsg; 
PCHAR pchBut; 
USHORT cbBuf; 
PUSHORT pcbMsg; 


Parameters 


Return Value 


Comments 


Restrictions 


See Also 


/x number of pointers in table x/ 
/« pointer to input message »/ 
/« number of bytes in input message x/ 
/x pointer to buffer for updated message __ «/ 
/« number of bytes in ‘buffer »/ 


/« pointer to variable for length of message »/ 


The DosInsMessage function copies a specified message to a buffer. Unlike the 
DosGetMessage function, DosInsMessage does not retrieve a message. Dos- 
InsMessage is often used when messages are loaded before the insertion-text 
strings are known. 


The DosInsMessage function is a family API function. 


ppchVTable Points to a table of pointers to null-terminated strings than can 
be inserted into the message. Up to nine strings can be given. 


usVCount Specifies the number of strings in the table. This parameter can be 
any value from 0 through 9. If this parameter is zero, the ppchVTable parameter 
is ignored. If this parameter is greater than 9, the function returns an error value 
indicating that the usVCount parameter is out of range. 


pszMsg_ Points to a null-terminated string that specifies the message to pro- 
cess. 


cbMsg Specifies the length (in bytes) of the message. 

pchBuf Points to the buffer that receives the message. 

cbBuf Specifies the length (in bytes) of the buffer that receives the message. 

pees Points to the variable that receives the number of bytes copied to the 
uffer. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MR_INV_IVCOUNT 
ERROR_MR_MSG_TOO_LONG 


As it copies a message, the DosInsMessage function replaces any symbol in the 
form %x (where x is a digit from 1 through 9) with one of the strings pointed to 
in the table pointed to by the ppchVTable parameter. For example, the function 
replaces all symbols of the form %1 with the first string pointed to in the table. 
If there is no corresponding string in the table, DosInsMessage copies the %x . 
sequence to the buffer. If the message is too long to fit in the buffer, the Dos- 
GetMessage function truncates the message and returns an error code. 


In real mode, the following restriction applies to the DosInsMessage function: 


@ There is no method of identifying the boot drive. The system assumes 
that the message file is in the root directory of the current drive. 


DosGetMessage, DosPutMessage 
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USHORT DoskKillProcess(fScope, pidProcess) 


USHORT fScope: 


PID pidProcess; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/» flag for process only-parent and child processes »/ 
/» process identifier of process to be ended »/ 


The DosKillProcess function terminates the specified process, with the option of 
also terminating all child processes that belong to it. Any subsequent request for 
the process’s termination code returns the TC_KILLPROCESS code, unless the 
process intercepted the termination request. 


fScope Specifies whether to terminate the child processes that belong to the 
specified process that is terminated. If this parameter is DKP_PROCESSTREE, 


‘the function terminates the specified process and all of its child processes. If it 


is DKP_PROCESS, the function terminates the specified process only. 
pidProcess Specifies the process identifier of the process to terminate. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_PROCID 


A process can intercept the termination request generated by the DosKill- 
Process function by using the DosSetSigHandler function to create a signal 
handler. When the process creates a signal handler, the process typically com- 
pletes any termination tasks, such as copying data from local buffers to files, 
then calls the DosExit function to terminate. If a process has no signal handler, 
the DosKillProcess function terminates the process after flushing all system file 
buffers and closing all handles opened by the process. 


Before terminating, the process being terminated must flush file buffers that are 
not managed by MS OS/2—for example, the buffers managed by the C run-time 
library. MS OS/2 does not flush these buffers as part of its termination 
sequence. 


This example creates the child process abc.exe, then calls the DosKillProcess 
function to terminate it: 

CHAR achFailName[128]; 

RESULTCODES resc; 


DosExecPgm(achFailName, sizeof (achFailName) , 
EXEC_ASYNCH, “abc ", 0, G&resc, "“abc.exe"); 


DosKillProcess (DKP_PROCESS, resc.codeTerminate) ; 


DosCwait, DosExit, DosSetSigHandler 
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™ DosLoadModule 
USHORT DosLoadModule ( pszFailName, cbFileName, pszModName, phmod) 


PSZ pszFailName; /» pointer to buffer for name if failure —«/ 
USHORT cbFileName; /« length of buffer for name if failure +/ 
PSZ pszModName; /« pointer to module name »/ 
PHMODULE phmod; /« pointer to variable for module handle «/ 


The DosLoadModule function loads a dynamic-link module and returns a handle 
for the module. You can use the module handle to retrieve the entry addresses 
of procedures in the module and to retrieve information about the module. 


Parameters pszFailName Points to the buffer that receives a null-terminated string. The 
DosLoadModule function copies a string to the buffer only if the function fails 
to load the module. The string identifies the dynamic-link module responsible for 
the failure. This module may be other than the one specified in the pszModName 
parameter if the specified module links to other dynamic-link modules. 


cbFileName Specifies the length (in bytes) of the buffer pointed to by the 
pszFailName parameter. 


pszModName Points to a null-terminated string. This string must be a valid 
MS OS/2 filename that specifies the path and filename of the dynamic-link 
module to be loaded. All dynamic-link modules have the .dll filename extension, 
by default. 


phmod Points to the variable that receives the handle of the dynamic-link 
module. . 


Return Value The return value is zero if the function is successful. Otherwise, it is an error . 
value, which may be one of the following: 


ERROR_BAD_FORMAT 
ERROR_FILE_NOT_FOUND 
ERROR_INTERRUPT 
ERROR_NOT_ENOUGH_MEMORY 


Comments The DosLoadModule function loads only MS OS/2 dynamic-link modules. 
. Attempts to load other executable files (such as MS-DOS executable files) result 
in errors. 


Example This example calls the DosLoadModule function to load the dynamic-link 
module ghdil.dll. This example then calls the DosGetProcAddr function to 
retrieve the address of the BOXMESSAGE function that is defined in the 
module. After calling the BOXMESSAGE function, the example calls Dos- 
FreeModule to free the dynamic-link module. (This example is accurate if 
ghdil.dil exists in a directory defined by the libpath parameter of the config.sys 
file, and if ghdll.dill contains the BOXMESSAGE function that uses the Pascal 
calling convention.) 


See Also 


DosLockSeg 
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CHAR achFailName [128]; 
HMODULE hmod; 
VOID (PASCAL FAR *pfnBoxMsg) (PSZ, BYTE, BYTE, SHANDLE, SHANDLE, BOOL); 


DosLoadModule (achFailName, /* failure name buffer a/ 
sizeof (achFailName) , /* size of failure name buffer */ 
"qhdll", /* module name */ 
&hmod) ; /* address of handle */ 


DosGetProcAdadr (hmod, "BOXMESSAGE", &pfnBoxMsg) ; 
pfnBoxMsg("Hello World", 0x30, 1, O, 0, FALSE); 
DosFreeModule (hmod) ; 


DosExecPgm, DosFreeModule, DosGetModName, DosGetProcAddr 


USHORT DosLockSeg(se/) 
SEL sel; /« selector of segment to lock «/ 


Parameters 
Return Value 


Comments 


See Also 


The DosLockSeg function locks a discardable segment in memory. A locked 
segment cannot be discarded until it is unlocked by using the DosUnlockSeg 
function. 


If a segment has been discarded, the DosLockSeg function returns an error 
value that specifies that the segment no longer exists. When this occurs, the 
DosReallocSeg function can be called to allocate a new copy of the segment. 
The program must recreate any discarded data. 


sel Specifies the selector of the segment to lock. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


DosLockSeg applies only to segments that have been allocated by using the 
DosAllocSeg function with the fAlloc parameter set to SEG_DISCARDABLE. 
MS OS/2 can move and swap a locked segment as needed. 


The DosLockSeg and DosUnlockSeg functions may be nested. For example, if 
DosLockSeg is called five times to lock a segment, DosUnlockSeg must be 
called five times to unlock the segment. A segment becomes permanently locked 
if it is locked 255 times without being unlocked. 


DosAllocSeg, DosReallocSeg, DosUnlockSeg 
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— DosMakeNmPipe 


USHORT DosMakeNmPipe (pszName, php, fsOpenMode, fsPipeMode, cbOutBuf, cbinBuf, ulTimeOut) 


PSZ pszName; /» pipe name »/ 
PHPIPE php; /« pointer to pipe handle »/ 
USHORT fsOpenMode; /« open mode of pipe »/ 
USHORT fsPipeMode; /« pipe-specific modes sf 
USHORT cbOutBuf: /« number of bytes in output buffer »/ 
USHORT cbinBuf; /« number of bytes in input buffer »/ 


ULONG u/TimeOut; 


Parameters 


/x timeout value x/ 


The DosMakeNmPipe function creates a named pipe and retrieves a handle that 
can be used in subsequent pipe operations. 


pszName Points to a null-terminated string that identifies the name of the 
pipe. The string must have the following form: 

\pipe\ame 

The string name, name, must have the same format as an MS OS/2 filename. 
php Points to the variable that receives the handle of the named pipe. 


fsOpenMode _ Specifies the modes with which to open the pipe. This param- 
eter is a combination of an access mode flag, an inheritance flag, and a write- 
behind flag. The possible values are: 


Value Meaning 
PIPE_ACCESS_DUPLEX Pipe is full duplex—going to and 
from server and client. 

PIPE_ACCESS_INBOUND Pipe is inbound—going from client 
to server. 

PIPE_ACCESS_OUTBOUND Pipe is outbound—going from server 
to client. 

PIPE_INHERIT Pipe is inherited by any child 


processes that are created by using 
the DosExecPgm function. 


PIPE_NOINHERIT Pipe is private to the current process 
and cannot be inherited. 

PIPE_LNOWRITEBEHIND Write-behind to remote pipes is not 
allowed. 

PIPE_WRITEBEHIND Write-behind to remote pipes is 
allowed. : 


fsPipeMode Specifies the pipe-specific modes of the pipe. This parameter is a 
combination of an instance count, a read-mode flag, a type flag, and a wait flag. 
The possible values are: 


Value Meaning 

PIPE_WAIT Reading from and writing to the pipe 
waits if no data is available. 

PIPE_LNOWAIT Reading from and writing to the pipe 


returns immediately if no data is 
available. 


Return Value 


See Also 


DosMakePipe 
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Value Meaning 
PIPE_LREADMODE_BYTE Read pipe as a byte stream. 
PIPE_LREADMODE_MESSAGE Read pipe as a message stream. 
PIPE_TYPE_BYTE Pipe is a byte-stream pipe. 
PIPE_TYPE_MESSAGE Pipe is a message-stream pipe. 
PIPE_LUNLIMITED_INSTANCES Unlimited instances of the pipe can 


be created. If this value is not 
specified, a value from 1 through 254 
can be used for the number of 
instances. 


cbOutBuf Specifies the number of bytes to reserve for the outgoing buffer. 
cbInBuf Specifies the number of bytes to reserve for the incoming buffer. 


ulTimeOut Specifies the default value (in milliseconds) of the timeout param- 
eter of the DosWaitNmPipe function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_OUT_OF_STRUCTURES 
ERROR_PATH_NOT_FOUND 
ERROR_PIPE_BUSY 


DosClose, DosWaitNmPipe 


USHORT DosMakePipe ( phfRead, phfWrite, cbPipe) 


PHFILE phfRead; 
PHFILE phfWrite; 
USHORT cbPipe; 


Parameters 


/x pointer to variable for read handle :/ 
/« pointer to variable for write handle «/ 
/« number of bytes reserved for pipe «/ 


The DosMakePipe function creates a pipe. The function creates the pipe, assign- 
ing the specified pipe size to the storage buffer, and also creates handles that the 
process can use to read from and write to the buffer in subsequent calls to the 
DosRead and DosWrite functions. 


phfRead Points to the variable that receives the read handle for the pipe. 


phfWrite Points to the variable that receives the write handle for the pipe. 


cbPipe Specifies the size (in bytes) to allocate for the storage buffer for this 
pipe. This parameter can be any value up to 65,536 minus the size of the pipe 
header, which is currently 32 bytes. If this parameter is zero, the default buffer 
size is used. 
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Return Value 


Comments 


See Also 


DosMemAvail 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_NOT_ENOUGH_MEMORY 
ERROR_TOO_MANY_OPEN_FILES 


Pipes are typically used by a pair of processes. One process creates the pipe and 
passes a handle to the other process. This lets one process write into the pipe 
and the other read from the pipe. Since MS OS/2 provides no permission 
checks on pipes, the cooperating processes must ensure that they do not attempt 
to write to or read from the pipe at the same time. 


When all of a pipe’s handles are closed by using the DosClose function, MS 
OS/2 deletes that pipe. If two processes are communicating by using a pipe and 
the process ends that is reading the pipe, the next call to the DosWrite function 
for that pipe returns the “broken pipe” error value. 


MS OS/2 temporarily blocks any call to the DosWrite function that would have 
written more data to the pipe than could fit in the storage buffer. The system 
removes the block as soon as enough data is read from the pipe to make room 
for the remaining unwritten data. 


DosClose, DosDupHandle, DosRead, DosWrite 


USHORT DosMemAvail( pu/Avai/Mem) 
PULONG pulAvailMem; /« pointer to variable for available memory «/ 


Parameters 
Return Value 


Comments 


Example 


The DosMemAvail function retrieves the size of the largest block of free mem- 
ory available when the function is called. The largest free block consists of all 
free memory, whether consecutive or not. This function does not cause segments 
to be moved, swapped, or discarded. 


pulAvailMem Points to the variable that receives the size (in bytes) of the 
largest free block of memory. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


Since other processes may allocate and free memory at any time, the size of the 
largest free block can be expected to change. 


The DosMemA vail function returns only the amount of memory currently avail- 
able without swapping. More memory can be allocated than indicated by the 
DosMemAvail function—when necessary, the system swaps memory or discards 
unlocked memory to meet memory-allocation requests. 


This example calls DosMemAvail to determine the amount of available memory. 
It then allocates one third of that memory and allows for reallocation of up to 
ten 64K segments. 
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#define SEGSIZE (64L * 1024L) 
LONG lAvail; 


SEL sel; 
eo ay ce at ce /* gets amount of current memory */ 
lAvail /= 3 /* calculate one third of memory */ 
DosAllosHuge ( (USHORT) (1Avail / SEGSIZE), /* number of segments x 
(USHORT) (lAvail % SEGSIZE), /* size of last segment */ 
é&sel, /* address of selector */ 
10, /* allows reallocation up to 640K */ 
SEG_NONSHARED) ; /* sharing flag * 
See Also DosAllocHuge 
DosMkDir 
USHORT DosMkDir( pszDirName, u/lReserved) 
PSZ pszDirName; /« new directory name «/ 
ULONG u/Reserved; /« must be zero »/ 
The DosMkDir function creates the specified directory. If the directory already 
exists or the specified directory name is invalid, the function returns an error 
value. 
The DosMkDir function is a family API function. 
Parameters pszDirName Points to a null-terminated string. This string must be a valid MS 
OS/2 directory name. 
ulReserved Specifies a reserved value; must be zero. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 
ERROR_ACCESS_DENIED 
ERROR_DRIVE_LOCKED 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 
Example This example calls the DosMkDir function to create the subdirectory abc and 
report an error if it fails: 
USHORT usError; 
usError = DosMkDir ("abc", OL); 
if (usError) 
VioWrtTTY ("Can't open directory\r\n", 22, 0); 
else { 
See Also DosRmDir 
DosMonClose 


USHORT DosMonClose(hmon) 
HMONITOR hmon:; /x monitor handle to close »/ 


The DosMonClose function closes the specified monitor. The function flushes 
and closes all monitor buffers associated with this process. 
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Parameters hmon__ Identifies the monitor to close. This handle must have been created pre- 
viously by using the DosMonOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MON_LINVALID_HANDLE 


See Also DosMonOpen, DosMonRead, DosMonReg, DosMonWrite 
~ DosMonOpen 

USHORT DosMonOpen( pszDevName, phmon) 

PSZ pszDevName; /x pointer to device name »/ 


PHMONITOR phmon; /» pointer to variable for monitor handle «/ 


The DosMonOpen function opens a monitor and creates a handle that can be 
used to identify the monitor. Only one monitor per process is allowed—that is, 
DosMonOpen must not be called more than once by any process. 


Parameters © pszDevName Points to a null-terminated string. This string specifies the name 
of the device for which the monitor is to be opened. 


phmon Points to the variable that receives the monitor handle. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MON_INVALID_DEVNAME 
ERROR_NOT_ENOUGH_MEMORY 


| Comments You can determine whether a device supports a monitor by using the DosDev- 
IOC# function. For more information, see DEV_-QUERYMONSUPPORT in 
Chapter 3, “Input-and-Output Control Functions.” 


See Also DosMonClose, DosMonRead, DosMonWrite 
DosMonRead 

USHORT DosMonRead{ pbinBuffer, fWait, pbDataBuf, pcbDataBuf) 
PBYTE pbinBuffer; /» pointer to buffer for monitor input —«/ 
UCHAR fWait; /» wait/no-wait flag »/ 
PBYTE pbDataBuf; /» pointer to buffer for data records s/ 


PUSHORT pcbDataBuf; /» pointer to variable with size of buffer »/ 


The DosMonRead function reads data records from the device associated with 
the specified monitor and copies the records to a buffer. 


Parameters pbInBuffer Points to the buffer for monitor input. This handle must have been 
registered previously by using the DosMonReg function. 
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fWait Specifies whether the function should wait for input. If this parameter is 
DCWW_WAIT, the function waits until input is ready. If this parameter is 
DCWW_NOWAITT, no input is ready, and the function returns immediately. 


pbDataBuf Points to the buffer that receives the data records. 


pcbDataBuf Points to the variable that contains the size (in bytes) of the 
buffer that receives the data records. When the DosMonRead function returns, 
it sets the variable to the number of bytes copied from the data record to the 
buffer. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MON_BUFFER_EMPTY 
ERROR_MON_BUFFER_TOO_SMALL 
ERROR_MON_INVALID_PARMS 


Comments Device monitors must respond rapidly to avoid delaying input and output (I/O). 
(This rapid response is especially important for keyboard monitors.) A monitor 
process should be written so that any threads that read and write the monitor 
data run at a high priority. These threads should never perform operations that 
might delay them, such as waiting for I/O or a semaphore. The monitor process 
can have other threads running at normal priority to handle such operations. 


See Also DosMonClose, DosMonOpen, DosMonReg, DosMonWrite 
DosMonReg 

USHORT DosMonReg(hmon, pbinBuf, pbOutBuf, fPosition, usindex) 

HMONITOR hmon; /« monitor handle to register »/ 

PBYTE pbinBuf; /» pointer to structure for input buffer  »/ 

PBYTE pbOutBuf: /« pointer to structure for output buffer »/ 

USHORT fPosition; /« position flag »/ 

USHORT us/ndex; /» index a/ 


The DosMonReg function registers a monitor by placing it in a chain of other 
monitors for the same device. Each monitor receives input from or sends output 
to the device in the order in which it appears in the chain. 


Parameters hmon Identifies the monitor to register. This handle must have been created 
previously by using the DosMonOpen function. 


pbInBuf Points to the MONIN structure that receives data from the device 
driver or from the previous monitor in the chain. The MONIN structure has the 
following form: 


typedef struct _MONIN { 
USHORT cb; 
BYTE abReserved [18] ; 
BYTE pBuf fer [108]; 

} MONIN; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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pbOutBuf Points to the MONOUT structure that receives data for the next 
monitor in the chain. The MONOUT structure has the following form: 
typedef struct _MONOUT { 

USHORT cb; 

BYTE abReserved [18]; 


BYTE abBuffer [108]; 
} MONOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


fPosition Specifies the position of the monitor in the chain of input and out- 
put. This parameter can be one of the following values: 


Value Meaning 
MONITOR_BEGIN Place the monitor at the beginning of the chain, 
* in front of any other monitors already in the 
chain. ; 
MONITOR_DEFAULT Place the monitor anywhere in the chain. 


MONITOR_END Place the monitor at the end of the chain, after 
any other monitors already in the chain. 


usIndex Specifies a device-specific value. If the device is the keyboard, this 
parameter specifies the identifier for the screen group to monitor. If no screen- 
group number is available (because the monitor is detached), the identifier of the 
current foreground screen group can be obtained by calling the DosGetInfoSeg 
function. (The current foreground screen group is the screen group that made - 
the most recent call to the KbdCharIn function.) 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MON_BUFFER_TOO_SMALL 
ERROR_MON_INVALID_HANDLE 
ERROR_MON_INVALID_PARMS 
ERROR_NOT_ENOUGH_MEMORY 


Comments The MONIN and MONOUT structures must be in the same segment. 

See Also ‘DosMonClose, DosMonOpen, DosMonRead, DosMonWrite, KbdCharIn 
DosMonWrite 

USHORT DosMonWrite (pbOutBuf, pbDataBuf, cbDataBuf) 

PBYTE pbOutBuf; /« monitor-output buffer »/ 

PBYTE pbDataBuf,; /« buffer from which records are taken «/ 

USHORT cbDataBuf, —_/« number of bytes / 


The DosMonWrite function writes one or more data records into a device’s out- 
put stream. The output-buffer structure identifies the device that receives the 
data records. 


Parameters pbOutBuf Points to the output-buffer structure for the monitor. The monitor 
must have been registered previously by using the DosMonReg function. 


Return Value 


Comments 


See Also 


DosMove 


DosMove 91 


pbDataBuf Points to the buffer that contains the data records to insert into 
the device’s output stream. 


cbDataBuf Specifies the number of bytes of data records in the buffer pointed 
to by the pbDataBuf parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MON_DATA_TOO_LARGE 
ERROR_MON_LINVALID_PARMS 


Device monitors must respond rapidly to avoid delaying input and output (I/O). 
(This rapid response is especially important for keyboard monitors.) A monitor 
process should be written so that any threads that read and write the monitor 
data run at a high priority. These threads should never perform operations that 
might delay them, such as waiting for I/O or a semaphore. The monitor process 
can have other threads running at normal priority to handle such operations. 


DosMonClose, DosMonOpen, DosMonRead, DosMonReg 


USHORT DosMove( pszO/dName, pszNewName, ulReserved) 


PSZ pszO/dName; 
PSZ pszNewName; 
ULONG u/Reserved: 


Parameters 


Return Value 


/« pointer to old path and filename «/ 
/« pointer to new path and filename «/ 
/« must be zero »/ 


The DosMove function moves a specified file to a specified new directory and/or 
filename. The function is often used to rename an existing file by moving the file 
to a new filename location in the same directory. The function can also be used 
to move a file to a new directory while preserving the existing filename or to 
rename any directory that is not the root directory. . 


The DosMove function is a family API function. 


pszOldName Points to a null-terminated string. This string specifies the 
current filename of the file to be moved. The string must be a valid MS OS/2 
filename. 


pszNewName Points to a null-terminated string. This string specifies the new 
directory and filename of the file to be moved. The string must be a valid MS 
OS/2 filename. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_NOT_SAME_DEVICE 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 
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Comments 


Example 


See Also 


The DosMove function cannot move a file from one drive to another; if a drive 
is used in the pszOldName string, the same drive must be used in the pszNew- 
Name string. 


Wildcard characters are not allowed in the filename. 


This example calls the DosMove function to move the file abc to the root direc- 
tory of the current drive and to rename the file xyz. This does not copy the file, 
but it may change the subdirectory that the filename appears in and may change 
the filename itself. 
DosMove("abc", /* old filename and path */ 

"\\xyz2", /* new filename and path * 

OL); /* reserved */ 


DosDelete, DosSelectDisk 


DosMuxSemWait 


USHORT DosMuxSemWait(pisemCleared, pmsxi, TimeOut) 
PUSHORT pisemCleared; /« pointer to variable for cleared semaphore »/ 


PVOID pmsxi; 
LONG /TimeOut; 


Parameters 


/« pointer to structure containing semaphore list «/ 
/« time-out value »/ 


The DosMuxSemWait function waits for one or more of the specified sema- 
phores to clear. The function first checks the semaphores specified in the list 
pointed to by the pmsxi parameter. If any of the semaphores in this list are 
clear, the function returns. Otherwise, the function waits until the time specified 
by the [TimeOut parameter elapses or until one of the semaphores in the list 
clears. 


The semaphore list can contain up to 16 semaphores. 


pisemCleared Points to the variable that receives the index number of the 
most recently cleared semaphore. 


pmsxl Points to the MUXSEMLIST structure containing a semaphore list that 
defines the semaphores to be cleared. The semaphore list consists of one or 
more semaphore handles. The MUXSEMLIST structure has the following form: 
typedef struct _MUXSEMLIST { 

USHORT cmxs; 


MUXSEM amxs [16]; 
} MUXSEMLIST; 


The structure may contain up to 16 semaphores. 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value 


Comments 


Example 
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ITimeOut Specifies how long to wait for the semaphores to become available. 
If the value is greater then zero, this parameter specifies the number of milli- 
seconds to wait before returning. If it is SEM_IMMEDIATE_RETURN, the 
function returns immediately. If it is SEM_INDEFINITE_WAIT, the function 
waits indefinitely. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 
ERROR_INTERRUPT 
ERROR_INVALID_EVENT_COUNT 
ERROR_INVALID_HANDLE 
ERROR_LINVALID_LIST_FORMAT 
ERROR_SEM_TIMEOUT 
ERROR_TOO_MANY_MUXWAITERS 


Although it is declared with the PVOID type, the second parameter of the 
DosMuxSemWait function must point to a MUXSEMLIST structure. You can 
create the structure by using the DEFINEMUXSEMLIST macro. The macro has 
the following syntax: 


DEFINEMUXSEMLIST(name, size) 


The name parameter specifies the name of the structure to be created, and the 
size parameter specifies the number of elements in the structure—that i is, the 
number of semaphores in the list. This macro creates an array of MUXSEMLIST 
structures. 


Unlike the other blocking semaphore functions (DosSemRequest, DosSem- 
SetWait and DosSemWait), DosMuxSemWait returns whenever one of the 
semaphores on its list is cleared, regardless of how long that semaphore may 
remain cleared. It is possible that the semaphore could be reset before the 
DosMuxSemWait function returns. 


The DosMuxSemWait function does not set or claim any of the semaphores. 


The DosMuxSemWait function can be used in conjunction with one or more 
semaphores as a triggering or synchronizing device. One or more threads can use 
DosMuxSemWait to wait for a semaphore. When an event occurs, another 
thread can clear that semaphore and immediately set it again. Any threads that 
waited for that semaphore by using DosMuxSemWsait will return. Threads that 
were waiting by using one of the “level-triggered” functions (DosSemRequest, 
DosSemSetWait, or DosSemWait) may or may not resume, depending on the 
scheduler’s dispatch order and the activity of other threads in the system. 


This example creates a structure of system semaphore handles for use by the 
DosMuxSemWait function. It sets the first element of the structure to the num- 
ber of handles stored and creates two semaphore handles. It then calls DosMux- 
SemWait to wait until one of the semaphores is cleared. It uses the value of the 
usSemIndex parameter to find out which semaphore is cleared, and if it is sema- 
phore 1, the example sets that semaphore. : 
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See Also 


DosNewSize 


DEFINEMUXSEMLIST(MuxList, 2) /* creates structure array */ 

USHORT usSemIndex; ‘ 

MuxList.cmxs = 2; 

DosCreateSem(CSEM_PUBLIC, &MuxList.amxs [0] .hsem, 
"\\sem\\timerO.sem") ; 

DosCreateSem(CSEM_PUBLIC, &MuxList.amxs[1].hsem, 
"\\sem\\timerl.sem") ; 


DosMuxSemWait (&usSemIndex, &MuxList, 500OL); 
if. (usSemIndex == 1 
DosSemSet (MuxList.amxs[1] .hsem) ; 


DosCreateSem, DosSemRequest, DosSemSet, DosSemSetWait, DosSemWait, 
WinMsgMuxSemWait 


USHORT DosNewSize (hf, u/NewSize) 


HFILE hf; 
ULONG u/NewSize; 


Parameters 


Return Value 


Comments 


Example 


/« file handle sf 
/» new size of file »/ 


The DosNewSize function changes the size of the specified file. The function can 
be used to truncate or extend a file. If a file is extended, the value of the new 
bytes is undefined. 


The DosNewSize function is a family API function. 


hf Identifies the file to be changed. This handle must have been created previ- 
ously by using the DosOpen function. 


ulNewSize Specifies the file’s new size (in bytes). 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DISK_FULL 
ERROR_LINVALID_HANDLE 
ERROR_INVALID_PARAMETER 
ERROR_LOCK_VIOLATION 
ERROR_NOT_DOS_DISK 


The DosNewSize function applies only to files that have been opened for writing. 
To change the size of a read-only file, first change the file’s attributes by using 
the DosSetFileMode function, then open the file for writing. 


If the function extends a file, the system will attempt to allocate sectors that are 
contiguous with the existing file sectors. 


This example opens the file abc and calls the DosNewSize function to set the 
file’s size to 100 bytes. If the file already exists and is larger than 100 bytes, it is 
truncated to 100 bytes. If the file is smaller than 100 bytes, or if it was created by 
using the DosOpen function, it is expanded to 100 bytes. 
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HFILE hf; 
USHORT usAction; 
DosOpen(“abco", &hf, &usAction, OL, FILE_NORMAL, 
FILE_OPEN | FILE_CREATE, 
OPEN_ACCESS_READWRITE | OPEN_SHARE_DENYREADWRITE, OL); 
DosNewSize({hf, 100L); 


See Also DosOpen, DosQFileInfo, DosSetFileMode 
DosOpen 
USHORT DosOpen( pszFileName, phf, pusAction, ulFileSize, usAttribute, fsOpenFlags, fsOpenMode, 
ulReserved) 
PSZ pszFileName; /« pointer to filename x/ 
PHFILE phf; /« pointer to variable for file handle »/ 
PUSHORT pusAction; /« pointer to variable for action taken «/ 
ULONG U/FileSize; /« file size if created or truncated »/ 
USHORT usAttribute; /« file attribute »/ 
USHORT fsOpenFlags; /« action taken if file exists/does not exist «/ 
USHORT fsOpenMode; /« open mode of file »/ 
ULONG u/Reserved; /x must be zero »/ 


The DosOpen function opens an existing file or creates a new file. This function 
returns a handle that can be used to read from and write to the file, as well as to 
retrieve information about the file. 


The DosOpen function is a family API function. 
Parameters pszFileName Points to the null-terminated string that specifies the name of 


the file to be opened. The string must be a valid MS OS/2 filename and must not 
contain wildcard characters. 


phf Points to the variable that receives the handle of the opened file. 


pusAction Points to the variable receiving the value that specifies the action 
taken by the DosOpen function. If DosOpen fails, this value has no meaning. 
Otherwise, it is one of the following values: 


Value Meaning 

FILE_CREATED File was created. 
FILE_EXISTED File already existed. 
FILE_TRUNCATED File existed and was truncated. 


ulFileSize Specifies the file’s new size (in bytes). This parameter applies only 
if the file is created or truncated. The size specification has no effect on a file 
that is opened only for reading. 


usAttribute Specifies the file attributes. This parameter can be a combination 
of the following values: . 


Value Meaning 
FILE_NORMAL File can be read from or written to. 
FILE_LREADONLY File can be read from, but not written to. 
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Value Meaning 

FILE_HIDDEN File is hidden and does not appear in a directory 
listing. oe 

FILE_SYSTEM File is a system file. 

FILE_ARCHIVED File has been archived. 


File attributes apply only if the file is created. 


fsOpenFlags Specifies the action to take both when the file exists and when it 
does not exist. This parameter may be one of the following values: 


Value Meaning 

FILE_CREATE Create a new file; fail if the file 
already exists. 

FILE_OPEN . Open an existing file; fail if the 
file does not exist. 

FILE_OPEN | FILE_CREATE Open an existing file or create the 
file if it does not exist. 

FILE_TRUNCATE Open an existing file and change 
to a given size. 

FILE_TRUNCATE | FILE_CREATE Open an existing file and truncate 
it, or create the file if it-does not 
exist. 


fsOpenMode Specifies the modes with which to open the file. It consists of 
one access mode and one share mode. The other values are option and can be 
given in any combination: 


Value Meaning 
OPEN_ACCESS_READONLY Data may be read from the file 
but not written to it. 
OPEN_ACCESS_READWRITE Data may be read from or written 
to the file. 
OPEN_ACCESS_WRITEONLY Data may be written to the file 
but not read from it. 
OPEN_SHARE_DENYNONE Other processes can open the file 


for any access: read-only, write- 
only, or read-write. 


OPEN_SHARE_DENYREAD Other processes can open the file 
for write-only access but they can- 
not open it for read-only or read- 
write access. 


OPEN_SHARE_DENYREADWRITE The current process has exclusive 
access to the file. The file cannot 
be opened by any process (includ- 
ing the current process). 


Value 


OPEN_SHARE_DENYWRITE 


OPEN_FLAGS_DASD 


OPEN_FLAGS_FAIL_ON_ERROR 


OPEN_FLAGS_NOINHERIT 


OPEN_FLAGS_WRITE_THROUGH 


DosOpen 


Other processes can open the file 
for read-only access but they can- 
not open it for write-only or 
read-write access. 


The file handle represents a physi- 
cal drive that has been opened for 
direct access. (The pszFileName 
parameter must specify a drive 
name.) The DosDevIOCtl func- 
tion can be used with this file han- 
dle to bypass the file system and 
to access the sectors of the drive 
directly. 


Any function that uses the file 
handle returns immediately with 
an error value if there is an I/O 
error—for example, when the 
drive door is open or a sector is 
missing. If this value is not 
specified, the system passes the 
error to the system critical-error 
handler, which then reports the 
error to the user with a hard-error 
popup. The fail-on-error flag is 
not inherited by child processes. 


The fail-on-error flag applies to all 
functions that use the file handle, 
with the exception of the Dos- 
DevIOCti function. 


The file handle is not available to 
any child process started by the 
current process. If this value is 
not specified, any child process 
started by the current process may 
use the file handle. 


This flag applies to functions, 
such as DosWrite, that write data 
to the file. If this value is spec- 
ified, the system writes data to the 
device before the given function 
returns. Otherwise, the system 
may store the data in an internal 
file buffer and write the data to 
the device only when the buffer is 
full or the file is closed. 


ulReserved Specifies a reserved value; must be zero. 
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Return Value 


Comments 


Restrictions 


Example 


See Also 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_CANNOT_MAKE 
ERROR_DISK_FULL 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_INVALID_ACCESS 
ERROR_INVALID_PARAMETER 
ERROR_NOT_DOS_DISK 
ERROR_OPEN_FAILED 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 
ERROR_TOO_MANY_OPEN_FILES 


The ERROR_ACCESS_DENIED value is returned if you try to open a file in a 
mode that is incompatible with the file’s current access and sharing modes—for 
example, if you attempt to open a read-only file for writing. This error is also 
returned if some other process has opened the file with a sharing method that 
denies the type of access you have requested. 


Once the file is opened, the DosSetFHandState function can be used to change 
the OPEN_FLAGS_FAIL_ON_ERROR, OPEN_FLAGS_NOINHERIT, and 
OPEN_FLAGS_WRITE_THROUGH flags specified in the fsOpenMode param- 
eter. 


MS OS/2 does not provide a built-in method to inform a child process that it has 
inherited a given file handle. The parent process must pass this information to a 
child process. If the file is created without the OPEN_FLAGS_NOINHERIT 
flag, and the parent process terminates without closing the file, the file will 
remain open until all child processes have terminated. 


In real mode, the following restriction applies to the DosOpen function: 


m™ Only the access modes and the OPEN_FLAGS_DASD flag may be 
specified for the fsOpenMode parameter. 


This example calls the DosOpen function to create a file abc that is 100 bytes 
long and open it for write-only access. The fsOpenFlags parameter is set to 
FILE_CREATE so that DosOpen will return an error if the file already exists. 


HFILE hf; 

USHORT usAction; 

Deapen tonnes: /* filename to open s/ 
&hf /* address of file handle */ 
&usAction, /* action taken * 
100L, /* size of new file */ 
FILE_NORMAL, /* file attribute */ 
FILE_CREATE, /* create the file */ 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, /* open mode */ 
OL) ; /* reserved * 


DosBufReset, DosChgFilePtr, DosDevIOCtl, DosDupHandle, DosExecPgm, 
DosQFHandState, DosQFileInfo, DosQFileMode, DosQFSInfo, DosSetFHand- 
State, DosSetFileMode 
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™ DosOpenQueue 


USHORT DosOpenQueue (ppidOwner, phqueue, pszQueueName) 

PUSHORT ppidOwner; /« pointer to variable for queue owner’s identifier »/ 
PHQUEUE phqueue; /» pointer to variable for handle of queue »/ 
PSZ pszQueueName; /» pointer to name of queue x/ 


The DosOpenQueue function opens a queue for the current process. 
Parameters ppidOwner Points to the variable that receives the process identifier of the 

queue owner. 

phqueue Points to the variable that receives the handle of the queue. 


pszQueueName Points to a null-terminated string. This string identifies the 
queue and must have the following form: 


\queues\name 


The string name, name, must have the same format as an MS OS/2 filename and 
must identify a queue that has been created previously by using the Dos- 
CreateQueue function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_NAME_NOT_EXIST 
ERROR_QUE_NO_MEMORY 


See Also _ DosCloseQueue, DosCreateQueue, DosReadQueue, DosWriteQueue 


H DosOpenSem_ . | 
USHORT DosOpenSem(phsem, pszSemName) 
PHSEM phsem; /« pointer to variable for semaphore handle «/ 


PSZ pszSemName; /x pointer to semaphore name »/ 


The DosOpenSem function opens a system semaphore of the specified name and 
returns a unique semaphore handle. The semaphore handle can then be used to 
set and clear the semaphore and to carry out other tasks that use the semaphore. 


Parameters phsem Points to the variable that receives the new semaphore handle. 


pszSemName Points to the null-terminated string that identifies the sema- 
phore. The string must have the following form: 


\sem\Viame 


The string name, name, must have the same format as an MS OS/2 filename and 
must identify a semaphore that has been created previously by using the Dos- 
CreateSem function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_NAME 
ERROR_SEM_NOT_FOUND | 
ERROR_TOO_MANY_SEMAPHORES 


EA 
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Comments The DosOpenSem function only returns the handle of the semaphore; it does 
not test or change the value of the semaphore. The semaphore handle is the 
same as the semaphore handle returned by the DosCreateSem function that 
created the semaphore. 

If a process creates a child process by using the DosExecPgm function, the new 
process inherits any open semaphore handles. 

Under MS OS/2, system semaphores reside in a memory buffer rather than a 
disk file. When the last process with an open semaphore terminates, that sema- 
phore is closed and is no longer available to any other process. 

Example This example calls the DosOpenSem function to open a system semaphore that 
had been created previously: 

HSEM hsem; 7* handle to semaphore */ 
DosOpenSem(&hsem, "\\sem\\abc.ext") ; /* opens the semaphore */ 
DosCloseSem(hsem) ; 7* closes the semaphore */ 

See Also DosCloseSem, DosCreateSem, DosExecPgm, DosSemClear, DosSemRequest 

DosPeekNmPipe 

USHORT DosPeekNmPipe (hp, pbBuf, cbBuf, pcbRead, pcbAvail, pfsState) 

HPIPE hp; /« pipe handle »/ 

PBYTE pbBuf; /» pointer to buffer for data »/ 

USHORT cbBuf; /» length of buffer for data »/ 

PUSHORT pcbReaqa; /« pointer to variable for number bytes read »/ 

PUSHORT pcbAvail; /» pointer to variable for number bytes available «/ 

PUSHORT pfsState; /« pointer to variable for pipe state x/ 

The DosPeekNmPipe function copies a pipe’s data into a buffer. 

Parameters hp Identifies the pipe to read from. 


pbBuf Points to a buffer that receives the data from the pipe. 


cbBuf Specifies the length (in bytes) of the buffer that receives the data from 
the pipe. 


pcebRead Points to the variable that receives a value specifying the number of 
bytes read from the pipe. 


pebAvail Points to the variable that the receives a value specifying the number 
of bytes that were available to be read. The first two bytes of this buffer specify 
the number of bytes remaining in the pipe (including message-header bytes). The 
next two bytes specify the number of bytes remaining in the current message. 
heal will be zero bytes remaining in the current message for a byte-stream 
pipe. 

pfsState Points to the variable that receives the state of the pipe. The state 
may be one of the following values: 
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Value Meaning 

PIPE_STATE_CLOSING The pipe is closed and can no longer 
be used. 

PIPE_STATE_CONNECTED The pipe has been opened and is 
available for reading and writing. 

PIPE_STATE_DISCONNECTED The serving end must call the Dos- 


ConnectNmPipe function to put the 
pipe into a listening state before a 
call to the DosOpen function will be 
accepted. A pipe is in a discon- 
nected state between a call to the 
DosMakeNmPipe function and a call 
to the DosConnectNmPipe function. 


PIPE_STATE_LISTENING The pipe will accept a call to the 
DosOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_PIPE_NOT_CONNECTED 


Comments The DosPeekNmPipe function never blocks, regardless of the blocking mode of 
the pipe. 


If the DosDisConnectNmPipe function has been called, the pipe will remain 
disconnected until a call is made to the DosConnectNmPipe function. 


See Also DosConnectNmPipe, DosDisConnectNmPipe, DosMakeNmPipe, DosRead 
DosPeekQueue 

USHORT DosPeekQueue (hqueue, pqresc, pcbElement, ppv, pusElementCode, fWait, pbElemPrty, hsem) 
HQUEUE hqueue; /« handle of queue to read from »/ 

PQUEUERESULT pqresc; /« pointer to structure for PID and request code +/ 

PUSHORT pcbE/lement; / pointer to variable for number of bytes s/ 

PVOID FAR * ppv; /» pointer to buffer for element received / 

PUSHORT pusE/ementCode; /» pointer to variable for element position »/ 

UCHAR /fWait; /« wait/no wait indicator «/ 

PBYTE pbElemPrty; /« pointer to variable for priority of element +/ 

ULONG hsem; /« semaphore handle s/ 


The DosPeekQueue function retrieves an element without removing it from a 
queue. It copies the address of the element to a pointer and fills a structure with 
information about the element. 


Parameters hqueue Identifies the queue to be read from. This handle must have been pre- 
viously created or opened by using the DosCreateQueue or DosOpenQueue 
function. 
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Return Value 


Comments 


See Also 


DPqresc_ Points to the structure that receives information about the request. The 
QUEUERESULT structure has the following form: 
typedef struct  QUEUERESULT { 

PID pidProcess; 


USHORT usEventCode; 
} QUEUERESULT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcbElement Points to the variable that receives the length in bytes of the ele- 
ment. 


ppv Points to a pointer that receives the address of the element in the queue. 


pusElementCode Points to the variable that specifies where to look in the 
queue for the element. If the pusElementCode parameter is 0x0000, the function 
looks at the beginning of the queue. Otherwise, the function assumes the value is 
an element identifier and looks for the element that immediately follows the 
specified element. When the function returns, it copies the identifier of the 
retrieved element to the variable. The element identifier can then be used to 
search for the next element or to read the given element from the queue. 


fWait Specifies whether the function should wait for an element to be placed 
in the queue, if the queue is empty. If the fWait parameter is DCWW_WAIT, 
the function waits until an element is available. If it is DCWW_NOWAIT, the 
function returns immediately. 


pbElemPrty Points to a variable that receives the priority value specified when 
the element was added to the queue. This is a numeric value from 0 through 15, 
15 is the highest priority. 


hsem Identifies a semaphore. This value can be the handle of a system sema- 


-phore that has been previously created or opened by using the DosCreateSem or 


DosOpenSem function, or it can be the address of a RAM semaphore. This 
semaphore would typically be used in a call to the DosMuxSemWait function to 
wait until the queue has an element. If the ia parameter is DCWW_WAIT, 
hsem is ignored. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_ELEMENT_NOT_EXIST 
ERROR_QUE_EMPTY 
ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_INVALID_WAIT 
ERROR_QUE_PROC_NOT_OWNED 


If the queue is empty, the DosPeekQueue function either returns immediately or 
waits for an element to be written to the queue, depending on the value of the 
fWait parameter. 


Only the process that created the queue may call the DosPeekQueue function. 


DosCreateQueue, DosCreateSem, DosMuxSemWait, DosOpenSem, DosOpen- 
Queue, DosReadQueue 
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— DosPhysicalDisk 
USHORT DosPhysicalDisk(usFunction, pbOutBuf, cbOutBuf, pbParmBuf, cbParmBuf) 


USHORT usFunction; /x action to take »/ 
PBYTE pbOutBuf; /« pointer to output buffer x/ 
USHORT cbOutBuf; /« Output-buffer length »/ 
PBYTE pbParmBuf; /» pointer to user-supplied information «/ 


USHORT cbParmBuf; /» length of user-supplied information «/ 


The DosPhysicalDisk function retrieves information about partitionable disks. 


Parameters usFunction Specifies the action to take. It can be one of the following values: 
Value Meaning 
INFO_COUNT_PARTITIONABLE_DISKS Retrieve the total number of 

partitionable disks. 
INFO_FREEIOCTLHANDLE | Release the handle obtained 
4 by a previous call to Dos- 
PhysicalDisk. 
INFO_GETIOCTLHANDLE Retrieve a handle to use 
with Category 9 IOCtl func- 
tions. 


pbOutBuf Points to the buffer that receives output information. For a full 
description, see the first list under “Comments.” 


cbOutBuf Specifies the length (in bytes) of the output buffer. 


pbParmBuf Points to a buffer that contains parameter data. For a full descrip- 
tion, see the second list under “Comments.” 


cbParmBuf. Specifies the length (in bytes) of the parameter buffer. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments When DosPhysicalDisk is used to obtain a handle to a partitionable physical 


drive (a usFunction value of INFO_.GETIOCTLHANDLE), the pbParmBuf 
parameter should point to a null-terminated string that contains the drive num- 
ber and a colon (:). The cbParmBuf parameter must contain the length of the 
entire string, including the trailing null character. For example, to obtain a han- 
dle for the first partitionable disk, pbParmBuf should point to “1:” and cbParm- 
Buf should be 3. 


The organization and content of the output buffer depend on the given function, 


as follows: 
Function cbOutBuf Returned information 
1 2 Total number of parti- 
tionable disks in system 
(one-based). 
ps 2 Handle for the specified 


partitionable disk for 
the Category 9 IOCtl 
functions. 

3 0 None. Pointer must be 
zero. | 


104 


Example 


See Also 


DosPortAccess 


DosPhysicalDisk 


This organization and content of the parameter buffer depend on the given func- 


tion, as follows: 
Function 


1 
2 


cbParmBuf 


0 
Length of string, includ- 
ing terminal null charac- 


Input parameters 


None. Must be zero. 
Null-terminated string 
that specifies the parti- 


ter tionable disk. The string 
must have the following 


form: 
number: 


The number parameter 
specifies the partition- 
able disk number. Parti- 
tionable disk numbers 
start at 1. 

Handle retrieved by 
function 2. 


This example calls the DosPhysicalDisk function to determine the total number 
of partitionable disks. The total value is placed in the usDataBuffer variable. 
USHORT usDataBuf fer; 


DosPhysicalDisk (INFO_COUNT_PARTITIONABLE_DISKS, 
(PBYTE) &usDataBuffer, /* address of data buffer 


2, /* length of data buffer * 
NULL, /* pointer to parameter list */ 
0); et A 


7* length of parameter list 


DosDevConfig, DosDevIOCtl 


USHORT DosPortAccess(usReserved, fRelease, usFirstPort, usLastPort) 


_ USHORT usReserved; 
USHORT fRelease; 

USHORT usFirstPort; 
USHORT usLastPort; 


Parameters 


/*« must be zero »/ 
/» request/release indicator »/ 
/« first port number x/ 
/« last port number x/ 


The DosPortAccess function requests or releases access to a port, or ports, for 
input/output privilege. 


usReserved Specifies a reserved value; must be zero. 


fRelease Specifies the type of access request. If this parameter is FALSE, the 
function requests access to a port. If it is TRUE, the function releases access to 
a port. 


usFirstPort Specifies either a single port or the starting port number (start-of- 
range) in a contiguous range. 


usLastPort Specifies either a single port or the ending port number (end-of- — 


- range) in a contiguous range. If only one port is being used, the usFirstPort and 


usLastPort parameters must be the same. 


Return Value 


Comments 


See Also 


DosPTrace 
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The return value is zero if the function is successful. Otherwise, it is an error 
value. 


Programs that perform input or output (I/O) to a port, or ports, in IOPL seg- 
ments must request port access from the operating system. 


Granting port access automatically grants cli and sti privileges from the operat- 
ing system. Therefore, there is no need to make an additional call to the Dos- 
CLiAccess function. 


DosCLiAccess 


USHORT DosPTrace(pvPtraceBuf) 


PVOID pvPtraceBuf; 


Parameters 


Return Value 


/« pointer to structure receiving register values «/ 


The DosPTrace function provides access to the MS OS/2 debugging functions. 
These debugging functions are available to any process that starts a protected- 
mode child process by using the DosExecPgm function with the fExecFlags 
parameter set to EXEC_TRACE. 


pvPtraceBuf Points to the PTRACEBUF structure that receives the current 
values of the child process’s registers and a code that indicates the reason for 
returning. The PTRACEBUF structure has the following form: 


typedef struct PTRACEBUF { 
PID pid; 
TID tid; 
USHORT omd; 
USHORT value; 
USHORT offv; 
USHORT segv; 
USHORT mte; 
USHORT rAX; 
USHORT rBX; 
USHORT rCx; 
USHORT rDX; 
USHORT rSI; 
USHORT rDI; 
USHORT rBP; 
USHORT rDS; 
USHORT rES; 
USHORT rIP; 
USHORT rCS; 
USHORT rF; 
USHORT rSP; 
USHORT rSS; 
} PTRACEBUE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_LINVALID_FUNCTION 
ERROR_LINVALID.PROCID 
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Comments To use the DosPTrace function, you need to provide the following function pro- 

totype in your source file: 
USHORT DosPTrace(PVOID); 

The DosPTrace function lets a parent process control the execution of the child 
process and access the child process’s memory directly to insert break points or 
change data. . 
The parent process starts the child process to be debugged, then stops the child 
process by using the DosPTrace function with the cmd field of the PTRACEBUF 
structure set to Ox000A. The parent process can then insert break points or 
change memory in the child process by using DosPTrace and the emd field 
values. Next, the parent process can start execution by setting the cmd field to 
0x0007 (go until break point) or 0x0009 (single step). The parent process can set ~ 
initial register values by setting cmd to 0x0006. After it is started, the child pro- 
cess returns control to the parent process if it encounters a break point, a non- 
maskable interrupt, a single-step interrupt, or the end of the program. 
The DosPTrace function can be used to debug a process with multiple threads 
by setting the tid field of the PTRACEBVUF structure to the identifier of the 
thread to be debugged. Other threads in the process are suspended. (The 
address space is the same for all threads in a process.) Commands to read from 
or write to memory locations or set break points affect all threads in the pro- 
cess, even if the command is issued with a specific thread identifier. If the 
parent process uses the 0x000B command, a selected thread or group of threads 
can keep running while others are suspended. This allows only the selected 
threads to be affected by the break points and manipulated. 

See Also ' DosExecPgm, DosGetInfoSeg 

DosPurgeQueue. 


USHORT DosPurgeQueue (hqueue) 


HQUEUE hqueue; 


Parameters 


Return Value 


Comments 
See Also 


/« handle of queue to be purged »/ 
The DosPurgeQueue function purges a queue of all elements. 


hqueue Identifies the queue to be purged. This handle must have been created 
previously by using the DosCreateQueue function. . 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_PROC_NOT_OWNED 


Only the process that created the queue may call the DosPurgeQueue function. 


DosCreateQueue 
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" DosPutMessage . 
USHORT DosPutMessage (hf, cbMsg, BEANEG) 


HFILE hf; 
USHORT cbMsg; 
PCHAR pchMsg; 


Parameters 


Return Value 


Comments 


Restrictions 


See Also 


a DosQAppType 


/« handle of output file/device »/ 
/« length of message buffer = «/ 
/x pointer to message buffer «/ 


The DosPutMessage function writes the message pointed to by the pchMsg 
parameter to the file identified by the hf parameter. 


The DosPutMessage function is a family API function. 
hf Identifies the file that receives the message. This handle must have been 


created previously by using the DosOpen function. Standard file handles (such 
as 1 and 2) can also be used. 


cbMsg_ Specifies the length (in bytes) of the message to output. 
pchMsg Points to the message to output. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_HANDLE 
ERROR_MR_UN_PERFORM 
ERROR_WRITE_PROTECT 


The DosPutMessage function uses.an 80-column screen width. If a word is 
about to span column 80, the function “wraps” the word to a new line at column 
1. If the last character to be positioned on a line is a double-byte character that 
would be bisected, this rule ensures that the character is not bisected. 


When handling word wrapping, the DosPutMessage function uses column 1 as 
the starting position of the cursor. 


In real mode, the following restriction applies to the DosPutMessage function: 


™ There is no method of identifying the boot drive. The system assumes 
that the message file is in the root directory of the current drive. 


DosGetMessage, DosInsMessage, DosOpen 


USHORT DosQAppType (pszPrgName, pusType) 


PSZ pszPrgName; 
PUSHORT pusType; 


Parameters 


/« pointer to executable-file name «/ 
/« pointer to application-type flags «/ 


The DosQAppType function retrieves the application type of an executable file. 
The application type is specified at link time in the module-definition file. 


pszPrgName Points to the null-terminated string that contains the name of the 
executable file for which the flags are to be returned. If the string appears to be 
a fully qualified path (that is, it contains a colon in the second position and/or 
contains a backslash), the file will be searched for in the indicated directory on 
the indicated drive. If neither of these conditions is true and the file is not in the 
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current directory, each drive and directory specification in the path defined in 
the current program’s environment will be searched. The default extension for 
an executable file is .exe, although any extension is acceptable. 


pusType Points to a word containing flags that specify the application type, as 
determined from the header of the executable file specified by the pszPrgName 
parameter. Upon return, the variable pointed to by the pusType parameter will 
have one or more of the following flags set: 


Value Meaning 


BOUND Application has been “bound” and can run 
either in protected mode or with MS-DOS 
(either the compatibility box or MS-DOS, 
version 3.x). 


DOSFORMAT Application will only run with MS-DOS. 

DYNAMICLINK Application is a dynamic-link module. 

NOTSPECIFIED Application type is not specified in executable 
header. . 

NOTWINDOCOMPAT Application will run only in a full screen ses- 
sion. 

WINDOWAPI Application runs as a Presentation Manager 
window. 

WINDOWCOMPAT Application will run in a VIO window. 

Return Value The return value is zero if the function is successful. Otherwise, it is one of the 
following values: 
ERROR_BAD_FORMAT 


ERROR_DRIVE_LOCKED 
ERROR_EXE_MARKED_INVALID 
ERROR_FILE_NOT_FOUND 
ERROR_INVALID_EXE_SIGNATURE 
ERROR_TOO_MANY_OPEN_FILES 


BM DosQCurDir 


USHORT DosQCurDir(usDriveNumber, pszPathBuf, pcbPathBuf) 

- USHORT usDriveNumber; /» drive number »/ 
PBYTE pszPathBuf; /« pointer to buffer receiving directory path —»/ 
PUSHORT pcbPathBuh /« pointer to variable receiving length of path »/ 


The DosQCurDir function retrieves the path of the current directory on the 
specified drive. DosQCurDir copies a null-terminated string identifying the 
current directory to the buffer pointed to by the pszPathBuf parameter. The 
string consists of one or more directory names separated by backslashes (\). 
The drive letter is not part of the returned string. 


The DosQCurDir function is a family API function. 
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Parameters usDriveNumber _ Specifies the drive number. The default drive is 0, drive A is 
1, drive B is 2, and so on. 


pszPathBuf _ Points to a buffer that receives the path of the current directory. 
The path of the current directory is copied to this buffer only if the buffer is 
large enough to contain the complete directory. 


pcbPathBuf Points to the variable that contains the size (in bytes) of the 
pszPathBuf buffer. If the buffer is too small to contain the current path, the 
error value ERROR _BUFFER_OVERFLOW is returned and this variable 
receives the size of the buffer required to contain the complete pathname. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_DRIVE_LOCKED 
ERROR_INVALID_DRIVE 
ERROR_NOT_DOS_DISK 
ERROR_NOT_READY 


. Example This example calls the DosQCurDisk function to retrieve the current drive num- 
ber, sets the buffer length to zero, and calls DosQCurDir. Since the buffer is too 
small to contain a path of any size, DosQCurDir returns the size needed in the 
cbPath variable. The DosAllocSeg function is called to allocate the memory 
needed for the buffer, and DosQCurDir is called again to retrieve the path 
name. This method of setting the buffer length will be successful in any version 
of MS OS/2, including future versions, in which the maximum path length may 
be longer. 

PSZ pszPath; 

USHORT cbPath, usDisk; 

ULONG ulDrives; 

SEL selPath; 


cbPath = 0; 
DosQCurDisk (&usDisk, &ulDrives) ; /* gets current drive */ 


/* First call DosQCurDir to find out the size of the buffer needed. a/ 
DosQCurDir (usDisk, NULL, &cbPath) ; 


DosAllocSeg(cbPath, &selPath, SEG —NONSHARED) ; /* allocates memory */ 
pszPath = MAKEP(selPath, 0); /* assigns it to a far pointer */ 
DosQCurDir (usDisk, /* drive number * 
pszPath, /* buffer for directory path af 
&cbPath) ; /* length of directory buffer */ 
See Also DosChDir, DosQCurDisk, DosSelectDisk 


DosQCurDisk 


USHORT DosQCurDisk( pusDriveNumber, pulLogicalDrives) 
’ PUSHORT pusDriveNumber; /» pointer to variable receiving drive number «/ 
PULONG pulLogical/Drives; /« pointer to variable receiving drive map __+/ 


The DosQCurDisk function retrieves the current drive number and a map of the 
logical drives. 


The DosQCurDisk function is a family API function. 
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Parameters 


Return Value 


Comments 


Example 


See Also 


pusDriveNumber _ Points to the variable that receives the number of the 
default drive. For example, drive A is 1, drive B is 2, and so on. 


pulLogicalDrives Points to the variable that receives the map of the logical 


_ drive. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The current drive number identifies the disk drive to be searched for a given file 
if no explicit drive name is given when the filename is specified. The current 
drive number is used by functions such as DosOpen and DosFindFirst. Each 
process has its own current drive and may change this drive, by using the Dos- 
ChDir function, without affecting other processes. The default current drive for 
a process is the drive on which the process is called. 


The map of the logical drives identifies which of the 26 possible disk drives exist. 
The map is a 32-bit value in which each bit of the low-order 26 bits represents a 
single drive. For example, bit 0 represents drive A, bit 1 represents drive B, and 
so on. If a bit is set to 1, the drive exists; if it is cleared to 0, the drive does not 
exist. 


This example calls the DosQCurDisk function to determine the current default 
drive and how many logical drives exist. The example then displays the letter of 
every logical drive after checking whether its bit is set in the ulDrives variable. 


CHAR chDrives; 
USHORT usDisk; 
ULONG ulDrives; 
DosQCurDisk (&usDisk, &ulDrives) ; /* gets current drive */ 
for (chDrives = 'A'; chDrives <= 'Z'; chDrives++) { 
if (ulDrives & 1) /* if the drive bit is set, */ 
VioWrtTTY (&chDrives, 1, 0); /* displays the drive letter */ 
ulDrives >>= 1; e 


DosChDir, DosFindFirst, DosOpen, DosQCurDir, DosSelectDisk 


DosQFHandState 


USHORT DosQFHandState (hf, pfsOpenMode 


HFILE hf; 


/«filehandle x/ 


PUSHORT pfsOpenMode; /» pointer to variable for file-handle state »/ 


Parameters 


The DosQFHandState function retrieves the state of the specified file handle. 
The file-handle state indicates whether the file may be read from or written to 
and whether it may be opened for reading or writing by other processes. 


The DosQFHandState function is a family API function. 


hf Identifies the file whose file-handle state is to be retrieved. This handle 
must have been previously created by using the DosOpen function. 
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pfsOpenMode Points to the variable that receives the file-handle state. The 
file-handle state consists of one access mode, one share mode, and optional 
flags. It is identical to the values specified in the fsOpenMode parameter of the 
DosOpen function. Which values are set can be determined by using the AND 
operator to combine the value returned in the pfsOpenMode parameter with one 


or more of the following values: 
Vaiue 


OPEN_ACCESS_READONLY 
OPEN_ACCESS_READWRITE 
OPEN_ACCESS_WRITEONLY 


OPEN_SHARE_DENYNONE 


OPEN_SHARE_DENYREAD 


OPEN_SHARE_DENYREADWRITE 


OPEN_SHARE_DENYWRITE 


OPEN_FLAGS_DASD 


OPEN_FLAGS_FAIL_ON_ERROR 


OPEN_FLAGS_NOINHERIT 


OPEN_FLAGS_WRITE_THROUGH 


Meaning 


Data may be read from the file 
but not written to it. 


Data may be read from or written 
to the file. 


Data may be written to the file 
but not read from it. 


Other processes can open the file 
for any access: read-only, write- 
only, or read-write. 


Other processes can open the file 
for write-only access but they can- 
not open it for read-only or read-. 
write access. 


The current process has exclusive 
access to the file. 


Other processes can open the file 
for read-only access but they can- 
not open it for write-only or 
read-write access. 


The file handle represents a physi- 
cal drive that has been opened for 
direct access. 


Any function that uses the file 
handle returns immediately with 
an error code if there is an I/O 
error. 


The file handle is private to the 
current process. 


The system writes data to the 


' device before the given function 


returns. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_HANDLE 
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Example 


See Also 


DosQFilelnfo 


This example calls the DosQFHandState function using the handle of a previ- 
ously opened file, and then checks the fsOpenMode variable and reports if the 
file is opened for read/write access: 


HFILE hf; 
USHORT fsOpenMode; 


DosQFHandState(hf, &fsOpenMode) ; 
if (fsOpenMode & OPEN_ACCESS _READWRITE) 

VioWrtTTY ("File opened for read/write access\r\n", 35, 0); 
if (fsOpenMode & OPEN_SHARE_DENYREADWRITE) | 

VioWrtTTY ("File cannot be shared\r\n", 23, 0); 


DosDevIOCtl, DosExecPgm, DosOpen, DosSetFHandState 


USHORT Dos@QFilelnfo (hf, usinfoLevel, pfstsinfo, cbinfoBuf) 


HFILE hf; /» handle of file about which data sought »/ 
USHORT usinfoLevel; /« level of file data required »/ 
PFILESTATUS pfstsinfo; /« pointer to file-data buffer «/ 
USHORT cbinfoBuf: /« length of file-data buffer «/ 


Parameters 


The DosQFileInfo function retrieves information about a specific file. The file 
information consists of the date and time the file was created, the date and time 
it was last accessed, the date and time it was last written to, the size of the file, 
and its attributes. 


The file information is based on the most recent call to the DosClose or Dos- 
BufReset function. 


The DosQFileInfo function is a family API function. 


hf Identifies the file about which information is to be retrieved. This handle 
must have been created previously by using the DosOpen function. 


usInfoLevel Specifies the level of file information required. In MS OS/2, ver- 
sion 1.1, this value must be 0x0001. 


pfstsInfo Points to the structure that receives the file information. The FILE- 
STATUS structure has the following form: 


typedef struct _FILESTATUS { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
FDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbhFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbInfoBuf Specifies the length (in bytes) of the buffer that receives the file 
information. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_INVALID_HANDLE 
ERROR_INVALID_LEVEL 


Example This example opens the file abc, calls the DosQFileInfo function to retrieve the 
current allocated size, and then calls the DosNewSize function to increase the 
file’s size by 1K: 


HFILE hf; 

USHORT usAction; 

FILESTATUS fstsFile; 

DosOpen("abco", &hf, &usAction, OL, FILE_NORMAL, 
FILE_OPEN | FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYNONE, OL); 


DosQFilelInfo (hf, /* file handle */ 
1, /* level of information */ 
(PBYTE) &fstsFile, /* address of file-data buffer */ 
sizeof (fstsFile)); /* size of data buffer * 
DosNewSize(hf, fstsFile.cbFileAlloc + 1024L); 
See Also DosBufReset, DosClose, DosOpen, DosQFileMode, DosSetFileInfo 
DosQFileMode 
USHORT DosQFileMode ( pszFileName, pusAttribute, ulReserved) 
PSZ pszFileName; /« pointer to filename »/ 
PUSHORT pusAttribute; /« pointer to variable for file attributes »/ 
ULONG u/Reserved: /» must be zero »/ 


The DosQFileMode function retrieves the attributes (mode) of the specified file. 
The file attributes are set when the file is created and can be changed at any time 
by using the DosSetFileMode function. 


The. DosQFileMode function is a family API function. 
Parameters pszFileName Points to a null-terminated string that specifies the name of the 
_ file to be checked. The string must be a valid MS OS/2 filename. 


pusAttribute Points to the variable that receives the file attributes. It can be 
one or more of the following values: 


Value Meaning 

FILELNORMAL File can be read from and written to. 

FILE_LREADONLY File can be read from but not written to. 

FILE_LHIDDEN File is hidden and does not appear in a directory 
listing. 

FILE_SYSTEM File is a system file. 

FILE_DIRECTORY File is a subdirectory. 


FILE_.ARCHIVED File has been archived. 
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ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 


Comments You cannot use the DosQFileMode function to retrieve the attributes of the 
volume label. The attributes of a volume label can be retrieved by using the 
DosQFSInfo function. 


Example This example calls the DosQFileMode function and displays a message if the 
filename abc is a subdirectory: 
USHORT usAttribute; 
DosQFileMode("abc", /* filename 7 
S&usAttribute, /* address of variable for file's attribute * 
OL); * reserved * 


if (usAttribute == FILE_DIRECTORY) 
VioWrtTTY("abc is a subdirectory\r\n", 23, 0); 


See Also DosQFHandState, DosQFSInfo, DosSetFileMode 


DosQFSiInfo 


USHORT DosQFSinfo(usDriveNumber, usinfoLevel, pbinfo, cbinfo) 
USHORT usDriveNumber; _—_/« drive number »/ 
USHORT usinfoLevel: /« type of information «/ 
PBYTE pbinfo; /« pointer to buffer for information »«/ 
USHORT cbinfo; /« length of information buffer «/ 


The DosQFSInfo function retrieves file-system information from the disk in the 
specified drive. This file-system information defines characteristics of the disk, 
such as its size. 


There are two levels of file-system information. Level 1 file-system information 
specifies the number of sectors per allocation unit on the disk, the number of 
allocation units, the available allocation units, and the number of bytes per sec- 
tor. Level 2 file-system information defines the volume label and the date and 
time at which the label was created. 


The DosQFSInfo function is a family API function. 


Parameters usDriveNumber _ Specifies the logical drive number for the disk about which 
information is to be retrieved. This parameter can be any value from 0 through 
26. If this parameter is zero, information about the disk in the current drive is 
retrieved. Otherwise, 1 specifies drive A, 2 specifies drive B, and so on. 


usInfoLevel Specifies the level of file information to be retrieved. In MS 
OS/2, version 1.1, this value can be 1 or 2. 
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pbInfo Points to the structure that receives the file-system information. For 
level 1 information, it points to an FSALLOCATE structure. For level 2, it 
points to an FSINFO structure. An FSALLOCATE structure has the following 
form: . 


typedef struct _FSALLOCATE { 
ULONG idFileSystem; 
ULONG cSectorUnit; 
ULONG cUnit; 
ULONG cUnitAvail; 
USHORT cbSector; 

} FSALLOCATE ; 


we: 


An FSINFO structure has the following form: 


typedef struct _FSINFO { 
FDATE fdateCreation; 
FTIME ftimeCreation; 
VOLUMELABEL vol; 

} FSINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbInfo Specifies the length (in bytes) of the buffer that receives the file-system 
information. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_DRIVE 
ERROR_INVALID_LEVEL 
ERROR_NO_VOLUME_LABEL 


Example This example calls the DosQFSInfo function and displays the volume label of 
. drive C: 
FSINFO fsinf; 
DosQFSInfo (3, /* drive number (c:) */ 
2, /* level of information requested */ 
(PBYTE) &fsinf, /* address of buffer 7 
sizeof (FSInfoBuf)); /* size of buffer’ 
VioWrtTTY(fsinf.vol.szVolLabel, fsinf.vol.cch, 0); 
See Also DosQFHandState, DosQFileMode, DosSetFSInfo 
DosQHandType 
USHORT DosQHandType (hf, pfsType, pusDeviceAttr) 
HFILE hf; / file handle »/ 
PUSHORT pfsType; /« pointer to-variable for handle type »/ 


PUSHORT pusDeviceAttr; /« pointer to variable for device attribute «/ 


The DosQHandType function retrieves information that specifies whether the 
given file handle identifies a file, device, or pipe. — 


Parameters hf Identifies the file. This handle must have been created previously by using 
the DosOpen function. 
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Return Value 


pfsType Specifies the type of file or device associated with the file handle. It 
can be one of the following: 


Value Meaning 


HANDTYPE_DEVICE The handle is to a device, such as a printer. 
HANDTYPE_FILE The handle is to a file. 
HANDTYPE_PIPE The handle is to a pipe. 


If the file or device is located on a network, this parameter is a combination of 
one of the values given above and the value HANDTYPE_NETWORK (0x8000). 


pusDeviceAttr Points to the variable that receives the device-driver attribute © 
word. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_HANDLE 
Comments The DosQHandType function allows some interactive or file-oriented programs 
to determine the source of their input. For example, the cmd.exe program 
suppresses the system prompt if the input is from a disk file. 
Example This example calls the DosQHandType function to determine if standard output 
; has been redirected to a file. The LOBYTE macro is an important part of this 
example; it allows the handle type to be determined even if the handle is to a file 
or device on a network: 
USHORT fsType, usDeviceAttr; 
DosQHandType (1, /* file handle */ 
&usHandType, /* type of handle */ 
&usDeviceAttr) ; /* device attribute */ . 
if (LOBYTE(fsType) == HANDTYPE_DEVICE 
‘VioWrtTTY ("stdout is a device\r\n", 20, 0); 
else if (LOBY SE (fsType) & HANDTYPE_FILE) { 
if (fsType & HANDTYPE_NETWORK) 
: VioWrtTTY ("stdout is a networked file\r\n", 28, 0); 
else 
) VioWrtTTY ("stdout is a local file\r\n", 24, 0); 
See Also DosOpen, DosQFHandState 
DosQNmPHandState 
USHORT DosQNmPHandState (hp, pfsState) 
HPIPE hp; /« pipe handle . «/ 
-_PUSHORT pfsState; /« pointer to variable receiving handle state «/ 


The DosQNmPHandState function retrieves information about the state of : a 
specified pipe handle. 
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Parameters hp Identifies the pipe to read from. 


pfsState Points to the variable that receives the handle state. This parameter is 
a combination of an instance count, a read-mode flag, a type flag, an end-point 
flag, and a wait flag. The possible values are: 


Value Meaning 

PIPE_LEND_CLIENT The handle is the client end of a 
named pipe. 

PIPE_END_SERVER The handle is the server end of a 
named pipe. 

PIPE_NOWAIT Reading from the pipe returns 


immediately if no data is available. If 
this flag is not set, reading from the 
pipe waits until data is available. _ 


PIPE_READMODE_MESSAGE Read the pipe as a message stream. 
If this flag is not set, the pipe is read 
as a byte stream. 


PIPE_TYPE_MESSAGE The pipe is a message-stream pipe. If 
: this flag is not set, the pipe is a 
byte-stream pipe. 
PIPE_UNLIMITED_INSTANCES Unlimited instances of the pipe can 
be created. If this flag is fiot spec- 
ified, a value from 1 through 254 can 
be used for the number of instances. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_PIPE_NOT_CONNECTED 


Comments If the handle is the server end of the pipe, the handle-state values are identical 
to those set by the call to the DosMakeNmPipe function that created the pipe. If 
the handle is the client end of the pipe, the handle-state values are determined 
by the DosOpen function that opened the pipe or are set by the DosSetNm- 
PHandState function. 


See Also DosMakeNmPipe, DosOpen, DosSetNmPHandState 
DosQNmPipelnfo 

USHORT DosQNmPipelinfo (hp, usinfoLevel, pbBuf, cbBuf) 

HPIPE hp; /« pipe handle «/ 

USHORT usinfoLevel; /« level of information to retrieve x/ 

PBYTE pbBuf; /« pointer to buffer receiving information «/ 

USHORT cbBuf; /« number of bytes in buffer »/ 


The DosQNmPipelInfo function retrieves information about a named pipe. 


Parameters hp Identifies the pipe to read from. 
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Return Value 


usInfoLevel Specifies the level of information to retrieve. Level 1 is miscel- 
laneous information about the pipe. Level 2 identifies the pipe’s clients. 


_ pbBuf Points to the buffer that receives the information. For level—-2 informa- 


tion, the buffer will contain a unique 2-byte identifier of the client. For level-1 
information, the data is stored in the PIPEINFO structure, which has the follow- 
ing form: 
typedef struct  PIPEINFO { 

USHORT cbOut; 

USHORT cbIn; . 

BYTE cbMaxInst; 

BYTE cbCurInst; 

BYTE cbhbName; 

CHAR szName[1]; 
} PIPEINEO; 


For more information, see Chapter 4, “Types, Macros, Structures.” 
cbBuf Specifies the size (in bytes) of the buffer receiving the information. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_BUFFER_OVERFLOW 
ERROR_INVALID_LEVEL 
ERROR_INVALID_PARAMETER 
ERROR_PIPE_NOT_CONNECTED 


See Also DosQNmPHandState, DosQNmPipeSemState 
DosQNmPipeSemState 

USHORT DosQNmPipeSemState (hsem, pbBuf, cbBuf) 

HSEM hsem; /» semaphore handle »/ 

PBYTE pbBuf; /x pointer to buffer receiving information «/ 

USHORT cbBuf; /« buffer size «/ 


Parameters 


Return Value 


See Also 


The DosQNmPipeSemState function returns information about all local named 
pipes that are in blocking mode and are associated with a specified system sema- 
phore. 

hsem Identifies the semaphore that is associated with the named pipe. 

pbBuf Points to the buffer that receives the information. 

cbBuf Specifies the length (in bytes) of the buffer that receives the informa- 
tion. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_SEM_NOT_FOUND 


DosSetNmPipeSem 
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HZ DosQSysinfo 


USHORT DosQSysinfo (index, pbSysinfoBuf, cbSysinfoBuf) 

USHORT index; /» index of value to look up »/ 
PBYTE pbSysinfoBuf, /« pointer to buffer receiving information »/ 
USHORT cbSysinfoBuf; /»« number of bytes in buffer receiving information «/ 


The DosQSysInfo function retrieves system-format information, such as max- 
imum path length, that is constant for a particular release of MS OS/2. 


Parameters index Specifies the index of the information to retrieve. In MS OS/2, version 
1.1, the only available index is zero, which returns the maximum path length 
(including the trailing null character). 


pbSysInfoBuf Points to the buffer that receives the system information. When 
the value of the index is zero, the DosQSysInfo function puts the maximum path 
length into the first two bytes of the buffer. 


cbSysInfoBuf Specifies the length (in bytes) of the buffer to receive the sys- 
tem information. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BUFFER_OVERFLOW 
ERROR_LINVALID_PARAMETER 


See Also DosGetVersion 


@ DosQueryQueue 
USHORT DosQueryQueue(hqueue, pusElemCount) 
HQUEUE hqueue; /« queue handle af 
PUSHORT pusElemCount; /» pointer to variable for element count «/ 


The DosQueryQueue function retrieves a count of the number of elements in the 
given queue. Any process that has a queue open can call this function. 


Parameters hqueue Identifies the queue about which information is sought. This handle 
must have been previously created or opened by using the DosCreateQueue or 
DosOpenQueue function. 


pusElemCount Points to the variable that receives the count of elements in 
the queue. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_QUE_INVALID_HANDLE 
See Also DosCreateQueue, DosOpenQueue 
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HZ DosQVerify 


USHORT DosOQVerify( pfVerifyOn) 


PBOOL pfVerifyOn; 


Parameters 


Return Value 


Example 


See Also 


/« verification-mode indicator «/ 
The DosQVerify function retrieves the verification mode. The verification mode 
specifies whether the system verifies the data each time it writes data to a disk. 
The DosQVerify function is a family API function. . 
pfVerifyOn Points to the variable that receives the verification mode. The 


pfVerifyOn parameter is set to TRUE if the system verifies the data. Otherwise, 
it is set to FALSE. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


This example calls the DosQVerify function to determine if write verification is 
active and then displays the result: 


BOOL fVerifyOn; 
DosQVerify (&fVerifyOn) ; 


if (fVerifyOn == TRUE) 

VioWrtTTY ("Verify mode is active\r\n", 23, 0); 
else 

VioWrtTTY ("Verify mode is not active\r\n", 27, 0); 
DosSetVerify 


a DosR2StackRealloc 


USHORT DosR2StackRealloc(usSize) 
USHORT usSize; /« new size for stack «/ 


The DosR2StackRealloc function changes the size of a thread’s ring—2 stack. 


-The function reallocates the stack as requested. 


Parameters 


Return Value 


This function cannot be used from ring 2. 


usSize Specifies the size (in bytes) of the ring-2 stack. The new stack size can- 
not be less than the current stack size. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


™@ DosRead 
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USHORT DosRead{(hf, pvBuf, cbBuf, pcbBytesRead) 


HFILE hf; 
PVOID pvBuf; 
USHORT cbBuf; 


/« file handle a/ 
/» pointer to buffer receiving data »/ 
/» number of bytes in buffer a/ 


PUSHORT pcbBytesRead; /« pointer to variable for number of bytes read «/ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The DosRead function reads up to a specified number of bytes of data from a 
file into a buffer. The function may read fewer than the specified number of 
bytes if it reaches the end of the file. 


The DosRead function is a family API function. 


hf Identifies the file to be read. This handle must have been created previously 
by using the DosOpen function. 


pvBuf Points to the buffer that receives the data. 
cbBuf Specifies the number of bytes to read from the file. 


pcbBytesRead Points to the variable that receives the number of bytes read 
from the file. This parameter is zero if the file pointer is positioned at the end of 
the file prior to the call to the DosRead function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_INVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NOT_DOS_DISK 


The DosRead function does not return an error if the file pointer is at the end of 
the file when the read operation begins. 


This example opens, reads, and displays the file abc: 


BYTE abBuf(512]; 

HFILE hf; 

USHORT usAction, cbhBytesRead, cbhBytesWritten; 

DosOpen("abco", &hf, &usAction, OL, FILE_.NORMAL, FILE_OPEN, 
OPEN_ACCESS_READONLY | OPEN USHARE_DENYNONE, OL); 


do { 

DosRead (hf, /* file handle a/ 
abBuf, * address of buffer */ 
sizeof(abBuf), /* size of buffer a 
&cbBytesRead) ; * address for number of bytes read */ 


DosWrite(1, abBuf, cbBytesRead, &cbBytesWritten) ; 
while (cbBytesRead) ; 


DosChgFilePtr, DosOpen, DosReadAsync, DosWrite, KbdStringIn 
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mM DosReadAsync 


USHORT DosReadAsync (hf, hsemRam, pusErrCode, pvBuf, cbBuf, pcebBytesRead) 


HFILE hf; /« file handle »/ 
PULONG hsemRam; /x pointer to RAM semaphore »/ 
PUSHORT pusErrCode; /« pointer to variable for error return code »/ 
PVOID pvBuf; /« pointer to input buffer »/ 
USHORT cbBuf; /» length of input buffer «/ 


PUSHORT pcbBytesRead; _—/« pointer to variable for number of bytes read «/ 


Parameters 


Return Value 


Comments 


The DosReadAsync function reads one or more bytes of data from the file 
identified by the hf parameter. The function reads the data asynchronously, that’ 
is, the function returns immediately to the process that called it but continues to 
copy data to the specified buffer while the execution of the process continues. 


hf Identifies the file to be read. This handle must have been previously opened 
by using the DosOpen function. 


hsemRam Points to the RAM semaphore that indicates when the function has 
finished reading the data. 


pusErrCode Points to the variable that receives any error code the function 
generates while reading data. The possible error codes are identical to those 
returned by the DosRead function. 


pvBuf Points to the buffer that receives the data being read. 


cbBuf Specifies the number of bytes to be read from the file identified by the 
hf parameter. 


pcebBytesRead Points to the variable that receives the number of bytes read 
from the file. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE © 
ERROR_INVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_DOS_DISK 


The DosReadAsync function reads up to the number of bytes specified in the 
cbBuf parameter, but it may read fewer if it reaches the end of the file. In any 
case, the function copies the number of bytes read to the variable pointed to by 
the pcbBytesRead parameter. The pcbBytesRead parameter is zero if all the bytes 
in the file have been read (that is, the end of file has been reached). 


If the process intends to use the RAM semaphore pointed to by the hsemRam 
parameter to determine when data is available, it must set the semaphore by 
using the DosSemSet function before calling DosReadAsyne. When Dos- 
ReadAsync has read the data, it clears the RAM semaphore. 


The DosReadAsync function carries out the asynchronous operation by creating 
a new thread that reads from the. specified file. The function terminates the 
thread when the operation is a or when an error occurs. 
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Example This example opens the file abc, sets a RAM semaphore, and calls the Dos- 

ReadAsync function to read part of the file. While the file is being read, program 
execution continues until the call to the DosSemWait function, which does not 
return until the DosReadAsync thread completes its work. 


BYTE abBuf [512]; 

ULONG hReadSemaphore = 0; 

HFILE hf; 

USHORT usAction, cbBytesRead; 

USHORT usReadReturn; 

DosOpen("abco", &hf, &usAction, OL, FILE_LNORMAL, FILE_OPEN, 
OPEN_ACCESS_READONLY | OPEN_ SHARE_ DENYNONE, OL); 


DosSemSet (&hReadSemaphore) ; /* sets RAM semaphore */ 
DosReadAsync (hf, /* handle to file */ 
&hReadSemaphore, /* address of semaphore */ 
&usReadReturn, /* address to store return code */ 
abBuf, /* address of buffer , */ 
sizeof (abBuf), /* size of buffer a/ 
&cbBytesRead) ; /* number of bytes read */ 


. /* other processing takes place here */ 


DosSemWait (&hReadSemaphore, -1L); 


See Also DosOpen, DosRead, DosSemSet, DosSemWait, Dos WriteAsync 
DosReadQueue 

USHORT DosReadQueue (hqueue, pqresc, pcbElement, ppv, usElement, fWait, pbElemPrty, hsem) 
HQUEUE hqueue; /« handle of queue to read »/ 
PQUEUERESULT pqresc; /+ pointer to structure for PID and request code «/ 

PUSHORT pcbElement; /« pointer to variable for length of element »/ 

PVOID FAR * ppv; /« pointer to buffer for element xf 

USHORT usElement; /« element number to read »/ 

UCHAR fWait; /» wait/no wait indicator x/ 

PBYTE pbElemPrty; /« pointer to variable for priority of element »/ 

HSEM hsem; /« semaphore handle x/ 


The DosReadQueue function retrieves an element from a queue and removes it 
from the queue. It copies the element to the buffer pointed to by the ppv param- 
eter and fills the structure pointed to by the pqresc parameter with information 
about the element. 


Parameters hqueue Identifies the queue to be read. This handle must have been previously 
created or opened by using the DosCreateQueue or DosOpenQueue function. 


pqresc Points to the structure that receives information about the request. The 
QUEUERESULT structure has the following form: 
typedef struct _QUEUERESULT { 
PID pidProcess; 
USHORT usEventCode; 
} QUEUERESULT; 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcbElement Points to the variable that receives the length in bytes of the ele- 
ment. ; 


ppv Points to a pointer that receives the address of the element in the queue. 
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Return Value 


Comments 


See Also 


usElement Specifies where to look in the queue for the element. If the us- 
Element parameter is 0x0000, the function looks at the beginning of the queue. 
Otherwise, the function assumes the value is an element identifier retrieved by 
using the DosPeekQueue function and looks for the specified element. 


fWait Specifies whether to wait for an element to be placed in the queue, if 
the queue is empty. If the fWait parameter is DCWW_WAIT, the function waits 
until an element is available. If it is DCWW_WNOWAIT, the function returns 
immediately with a code that indicates there are no entries in the queue. 


pbElemPrty _ Points to a variable that receives the priority value specified when 
the element was added to the queue. This is a numeric value from 0 through 15; 
15 is the highest priority. . 


hsem Identifies a semaphore. This value can be the handle of a system sema- 
phore that has been previously created or opened by using the DosCreateSem or 
DosOpenSem function, or it can be the address of a RAM semaphore. This 
semaphore. would typically be used in a call to the DosMuxSemWait function to 
wait until the queue has an element. If the fWait parameter is DCWW_WAIT, 
hsem is ignored. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_ELEMENT_NOT_EXIST 
ERROR_QUE_EMPTY 
ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_INVALID_WAIT 
~ ERROR_QUE_PROC_NOT_OWNED 


If the queue is empty, the DosReadQueue function either returns immediately or 
waits for an element to be written to the queue, depending on the value of the 
{Wait parameter. 


Only the process that created the queue may call the DosReadQueue function. 


DosCreateQueue, DosMuxSemWait, DosOpenQueue, DosPeekQueue, Dos- 
WriteQueue 


DosReallocHuge 
USHORT DosReallocHuge (usNumSeg, usPartialSeg, sel) 


USHORT usNumSeg; 


/« number of 65, 536-byte segments «/ 


USHORT usPartia/Seg; /« number of bytes in last segment +/ 


SEL se/; 


/« segment selector x/ 


The DosReallocHuge function reallocates a huge memory block. The function 
changes the size of the huge memory to the number of 65,536-byte segments 
specified by the usNumSeg parameter plus an additional segment of the size 
specified by the usPartialSeg parameter. . 


_ The DosReallocHuge function is a family API function. 


Parameters 


Return Value 


Comments 


Restrictions 


See Also 


DosReallocSeg 
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usNumSeg Specifies the number of 65,536-byte segments to allocate. 


usPartialSeg Specifies the number of bytes in the last segment. This number 
can be any value from 0 through 65,535. If it is zero, no additional segment is 
allocated. 


sel Specifies the selector for the huge memory block to be reallocated. The 
selector must have been created previously by using the DosAllocHuge function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


The DosReallocHuge function does not change the sharable and discardable 
attributes of the segments in the huge memory block. If it was originally a shar- 
able or discardable block, it remains a sharable or discardable block. However, 
if DosReallocHuge reallocates a discardable block, it also locks the segments. 
The DosUnlockSeg function must be used to unlock the segments and permit 
discarding. 


The memory block cannot be reallocated for a size larger than the maximum 
specified by the usMaxNumSeg parameter in the original call to the DosAlloc- 
Huge function. 


Each segment in the huge memory block has a unique selector. The selectors are 
consecutive. The sel parameter specifies the value of the first selector; the 
remaining selectors can be computed by adding the selector offset to the first 
selector one or more times—that is, once for the second selector, twice for the 
third, and so on. The selector offset is a multiple of 2, as specified by the shift 
count retrieved by using the DosGetHugeShift function. For example, if the shift 
count is 2, the selector offset is 4 (1 << 2). If the selector offset is 4 and the 
first selector is 6, the second selector is 10, the third is 14, and so on. 


In real mode, the following restriction applies to the DosReallocHuge function: 


@ The usPartialSeg parameter is rounded up to the next paragraph (16-byte) 
value. 


DosAllocHuge, DosFreeSeg, DosGetHugeShift, DosLockSeg, DosReallocSeg, 
DosUnlockSeg 


USHORT DosReallocSeg(usNewSize, se/) 


USHORT usNewSize; 


SEL sel; 


/« new segment size »/ 
/« segment selector «/ 


The DosReallocSeg function reallocates a segment. The function changes the 
size of the segment to the number of bytes specified in the usNewSize parameter. 


The DosReallocSeg function is a family API function. 


126 DosReallocSeg 


Parameters 


Return Value 


Comments 


Restrictions 


See Also 


usNewSize Specifies the new size (in bytes). The size can be any number from 
0 through 65,535. If it is zero, the function allocates 65,536 bytes. 


sel Specifies the selector of the segment to be reallocated. The selector must 
have been created previously by using the DosAllocSeg function. 


The return value is zero if the function is successful. Otherwise, it is an error — 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_NOT_ENOUGH_MEMORY 


The DosReallocSeg function does not change the sharable and discardable attri- 
butes of the segment. If it was originally a sharable or discardable segment, it 
remains a sharable or discardable segment. 


However, if DosReallocSeg reallocates a discardable segment, it also locks the 
segment. You must use the DosUnlockSeg function to unlock the segment and 
permit discarding. 


The DosReallocSeg function cannot reallocate a shared seement to a size 
smaller than its original size. 


In real mode, the following restriction applies to the DosReallocSeg function: 


mM The usNewSize parameter is rounded up to the next paragraph (16-byte) - 
value. 


DosAllocSeg, DosFreeSeg, DosLockSeg, DosReallocHuge, DosUnlockSeg 


DosResumeThread 


USHORT DosResumeThread (tid) 
TID tid; /« identifier of thread to be resumed «/ 


Parameters 


Return Value 


See Also 


The DosResumeThread function restarts a thread that was previously stopped by 
the DosSuspendThread function. 


tid Specifies the thread identifier of the thread to be resumed. The thread 
must have been created previously by using the DosCreateThread function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_THREADID 
DosCreateThread, DosSuspendThread 
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@ DosRmDir 


USHORT DosRmDir(pszDirName, u/Reserved) 
PSZ pszDirName; /« directory name «/ 
ULONG u/Reserved; /» must be zero «/ 


The DosRmDir function removes the specified directory. The directory must be 
empty before it can be removed; that is, it must not contain files of any kind, 
including hidden files and other directories. If the specified directory cannot be 
found or is not empty, DosRmDir returns an error. 


The DosRmDir function is a family API function. 


Parameters pszDirName Points to a null-terminated string that specifies the directory to 
be removed. This string must be a valid MS OS/2 directory name. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_CURRENT_DIRECTORY. 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 


Comments The DosRmDir function cannot remove the current directory or the root direc- 
tory. 


If necessary, use the DosDelete function to remove files from the directory. 


Example This example deletes all files in the subdirectory abc and then calls the DosRm- 
Dir function to delete the subdirectory. If the subdirectory contains other sub- 
directories or files that cannot be deleted, the DosRmDir function returns an 
error. 


USHORT usError; 


DosDelete("abc\\*.*#", OL); /* removes all files * 
usError = DosRmDir("abc", OL); /* removes subdirectory */ 
if (usError) 

ar ate delete subdirectory\r\n", 27, 0); 
else 


See Also DosChDir, DosDelete, DosMkDir 
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HM DosScanEnv 


USHORT DosScanEnv(pszVarName, ppszResult) 
PSZ pszVarName; /« pointer to environment-variable name »/ 
PSZ FAR * ppszResult; /« pointer to variable for result pointer —»/ 


The DosScanEnvy function searches an environment for a specified environment 
variable. The environment is one or more null-terminated strings that name and 
define the environment variables available to the current process. Environment 
variables can be used to pass information to a program—for example, a variable 
might name a list of directories that contain data files to be used by the program. 


An environment variable has the following form: 
name=value 


The DosScanEnvy function searches for the environment variable whose name 
matches the name pointed to by the pszVarName parameter. If DosScanEnv 
finds the variable, it copies the address of the first character of the environment 
variable’s value to the variable pointed to by the ppszResult parameter. The first 
ae of the environment variable’s value is the character following the equal 
sign (=). 


Parameters pszVarName Points to a null-terminated string that specifies the name of an 
environment variable. The string must not include a trailing equal sign (=), since 
the equal sign is not part of the name. . 


ppszResult Points to the pointer variable that receives the address of the 
environment string. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. . 
See Also DosExecPgm, DosGetEnv, DosSearchPath 


™ DosSearchPath 
USHORT DosSearchPath( fsSearch, pszPath, pszFileName, pbBuf, cbBuf) 


USHORT fsSearch; /» search flags »/ 
PSZ pszPath; /« pointer to search path or environment variable «/ 
PSZ pszFileName; /x pointer to filename »/ 
PBYTE pbBuf;: /« pointer to result buffer »/ 
USHORT cbBuf; /» length of result buffer »/ 


The DosSearchPath function searches the specified search path for the given 
filename. A search path is a null-terminated string that consists of a sequence of 
directory paths separated by semicolons (;). The function searches for the 


filename by looking in each directory (one directory at a time) in the order 
given. 


Parameters 


Return Value 


Comments 
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fsSearch Specifies how to interpret the pszPath parameter and whether or not 
to search the current directory. This parameter can be a combination of the fol- 
lowing values: 


Value Meaning 


SEARCH_CUR_DIRECTORY The function searches the current direc- 
tory before it searches the first directory 
in the search path. If this value is not 
specified, the function searches the 
current directory only if it is explicitly 
given in the search path. 


SEARCH_EN VIRONMENT _ The pszPath parameter points to the 
name of an environment variable. The 
function retrieves the value of the 
environment variable from the process’s 
environment segment and uses it as the 
search path. If this value is not specified, 
pszPath points to a string that specifies 
the search path. 


SEARCH_PATH The pszPath parameter specifies the 
search path. This value cannot be used 
with the SEARCH_EN VIRONMENT 
value. 


pszPath Points to a null-terminated string that specifies the search-path refer- 
ence. . 


pszFileName Points to a null-terminated string that specifies the filename to 
search for. The string must be a valid MS OS/2 filename and can contain wild- 
card characters. 


pbBuf Points to the buffer that receives the full pathname of the file if the 
filename is found. 


cbBuf Specifies the length in bytes of the structure that is pointed to by the 
pbBuf parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The DosSearchPath function uses the search path pointed to by the pszPath 
parameter to look for the filename pointed to by the pszFileName parameter. 
The pszPath parameter can point to an environment variable name, such as 
PATH or DPATH, or it can point to a search path (as specified by the fsSearch 
parameter). The filename must be a valid MS OS/2 filename and can contain 
wildcard characters. If DosSearchPath finds a matching filename in any of the 
directories specified by the search path, the function copies the full, null- 
terminated pathname to the buffer pointed to by the pbBuf parameter. If the 
filename pointed to by the pszFileName parameter contains wildcard characters, 
the resulting pathname will also contain wildcard characters; the DosFindFirst 
function can be used to retrieve the actual filename(s). 


The DosSearchPath function does not check for the validity of filenames. If the 
filename is not valid, the function returns an error indicating that the file was not 
found. 
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Example 


See Also 


DosSelectDisk 


This example uses the search path specified by the DPATH environment variable 
to search for the abc.txt filename: 


CHAR szFoundFile [128]; 
DosSearchPath (SEARCH_ENVIRONMENT, /* uses environment variable «7. 


"“DPATH", | /* uses DPATH search path © */ 
"aboe.txt", /* filename * 
szFoundFile, /* receives resulting filename */ 
sizeof (szFoundFile)); /* length of result buffer * 


The following example is identical to the first example if the DPATH variable is 
defined as shown: 


DPATH=c:\sysdir;c:\init 


DosSearchPath (SEARCH_ PATH, /7* uses search path */ 
"oe: \\sysdir; o:\\init", /* search path */ 
"abo.txt" /* filename */ 
szFoundFile, /* receives resulting filename */ 
sizeof (szFoundFile)) ; /* length of result buffer * 


DosFindFirst, DosScanEny 


USHORT DosSelectDisk( usDriveNumber) 
USHORT usDriveNumber, __/» default-drive number »/ 


Parameters 


Return Value 


Example 


See Also 


The DosSelectDisk function selects the specified drive as the default drive for 
the calling process. 


The DosSelectDisk function is a family API function. 


usDriveNumber _ Specifies the number of the default drive. Drive A is 1, drive 
B is 2, and so on. 


The return value is zero if the function i is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_DRIVE 


This example calls the DosSelectDisk function to change the default drive to 
drive C. It then changes the default path to the root and opens the file abc. txt. 


HFILE hf; 

USHORT usAction; ; 

DosSelectDisk (3); /* selects drive C: */ 
DosChDir ("\\", OL); /* changes to the root directory */ 


DosOpen("abc.txt", &hf, S&usAction, OL, FILE_NORMAL, 
FILE_OPEN | FILE_ CREATE, 
OPEN_ACCESS_READWRITE | OPEN _SHARE_DENYWRITE, OL); 


DosChDir, DosQCurDisk 
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™ DosSelectSession 
USHORT DosSelectSession (idSession, ulReserved) 
USHORT idSession: /« session identifier »/ 
ULONG u/Reserved; /« must be zero »/ 


The DosSelectSession function switches the specified child session to the fore- 
ground. Only the parent session can call DosSelectSession to switch a session, 
and the parent session, or one of its descendant sessions, must be currently exe- 
cuting in the foreground when DosSelectSession is called. If the parent session 
is not in foreground, it can use DosSelectSession to switch itself to the fore- 
ground. 


Parameters idSession Specifies the identifier of the session to be switched to the fore- . 
ground. This identifier must have been created previously by using the DosStart- 
Session function. If idSession is 0x0000, the function switches the parent session 
to the foreground. 


ulReserved Specifies a reserved value; must be zero. 


Return Value ‘The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments The DosSelectSession function can only select a child session that was created 


by using the DosStartSession function with the Related field of the START- 
DATA structure set to TRUE. In other words, this function cannot select ses- 
sions started as independent sessions. 


See Also DosSetSession, DosStartSession, DosStopSession 


—H DosSemClear. 


USHORT DosSemClear(hsem) | 
HSEM hsem; /x semaphore handle «/ 


The DosSemClear function clears a system or RAM semaphore that has been 
set by using the DosSemRequest, DosSemSet, or DosSemSetWait function. 


Parameters hsem Identifies the semaphore to set. This value can be the handle of a 
system semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 
ERROR_INVALID_HANDLE 


Comments The DosSemClear function cannot clear a system semaphore that is owned by 
another process unless the semaphore is nonexclusive. 
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Example 


See Also 


This example uses the DosSemClear function to clear a RAM semaphore and a 
system semaphore: 


ULONG hsem = O; 

HSYSSEM hsys; : 

DosSemClear (&hsem) ; /* clears a RAM semaphore * 
DosSemClear (&hsys) ; /* clears a system semaphore */ 


DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemRequest, DosSem- 
Set, DosSemWait 


DosSemRequest 


USHORT DosSemRequest(hsem, /TimeOut) 


HSEM hsem; 
LONG /TimeOut; 


Parameters 


Return Value 


Comments 


/« semaphore handle +/ 
/« time-out s/ 


The DosSemRequest function requests that the specified semaphore be set as 
soon as it is clear. If no previous thread has set the semaphore, DosSemRequest 
sets the semaphore and returns immediately. If the semaphore has already been 
set by another thread, the function waits until a thread clears the semaphore (by 
using the DosSemClear function) or until a time-out occurs. 


hsem Identifies the semaphore to set. This value can be the handle of a 
system semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


lITimeOut Specifies how long to wait for the semaphore to clear. If the value 
is greater then zero, this parameter specifies the number of milliseconds to wait 
before returning. If the value is SEM_IMMEDIATE_RETURN, the function 
returns immediately. If the value is SEM_INDEFINITE_WAIT, the function 
waits indefinitely. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INTERRUPT 
ERROR_INVALID_HANDLE 
ERROR_SEM_OWNER_DIED 
ERROR_SEM_TIMEOUT 
ERROR_TOO_MANY_SEM_REQUESTS 


The effects of DosSemRequest are cumulative. If multiple calls to DosSem- 
Request set the semaphore, the same number of calls to the DosSemClear func- 
tion are required to clear the semaphore. 


If more than one thread has requested to set the semaphore, a thread may have 
to wait through several changes of the semaphore before it continues (depending 
on which thread clears the semaphore and when the system scheduler passes 
control to the thread). As long as the semaphore is set (even if it has been 
cleared and reset since the thread originally called the function), the thread must 
wait. . 


Example 


See Also 


DosSemSet 
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The DosSemRequest function cannot set a system semaphore that is set by 
another process, unless the semaphore is nonexclusive. 


The DosSemRequest function can set system or RAM semaphores. A system 
semaphore is initially clear when it is created. A RAM semaphore is clear if its 
value is zero. Programs that use RAM semaphores should assign the initial value 
of zero. 


This example uses the DosSemRequest function to create a RAM semaphore. It 
also shows how to set and clear the semaphore. 


ULONG hsem = OQ; 


DosSemRequest (&hsem, /* address of handle */ 
-1L); /* waits indefinitely */ 
DosSemC lear (&hsem) ; /* clears the semaphore */ 


DosCreateSem, DosExitList, DosMuxSemWait, DosOpenSem, DosSemClear, 
DosSemSet, DosSemSetWait, DosSemWait 


USHORT DosSemSet(hsem) 


HSEM hsem; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/« semaphore handle «/ 


The DosSemSet function sets a specified semaphore. A process typically uses 
this function to set a semaphore, then waits for the semaphore to clear by using 
the DosSemWait or DosMuxSemWait function. 


hsem Identifies the semaphore to set. This value can be the handle of a 
system semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 
ERROR_LINVALID_HANDLE 
ERROR_TOO_MANY_SEM_REQUESTS 


The DosSemSet function cannot set a system semaphore that is owned by 
another process unless the semaphore is nonexclusive. 


This example uses the DosSemSet function to set a RAM semaphore and a sys- 
tem semaphore: 


ULONG hsem = 0; 

HSYSSEM hsys; 

DosSemSet (&hsem) ; /* sets a RAM semaphore */ 
DosSemSet (hsys) ; /* sets a system semaphore */ 


DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSem- — 
Request, DosSemSetWait, DosSemWait 
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DosSemSetWait 
USHORT DosSemSetWait (hsem, /TimeOut) 


HSEM hsem; 
LONG /TimeOut; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/x semaphore handle «/ 
/« time-out s/ 


The DosSemSetWait function sets the specified semaphore (if it is not already 
set) and then waits for another thread to clear the semaphore (by using the Dos- 
SemClear function) or for a time-out to occur. The only difference between the 
DosSemSetWait function and the DosSemWait function is that the DosSem- 
SetWait function will first set the semaphore if it is not already set. 


hsem Identifies the semaphore to set. This value can be the handle of a 
system. semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


ITimeOut Specifies how long to wait for the semaphore to become clear. If 
the value is greater then zero, this parameter specifies the number of mil- 
liseconds to wait before returning. If it is SEM_IMMEDIATE_RETURN, the 
function returns immediately. If it is SEM_INDEFINITE_WAIT, the function 
waits indefinitely. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 
ERROR_INTERRUPT 
ERROR_INVALID_HANDLE 
ERROR_SEM_TIMEOUT 
ERROR_TOO_MANY_SEM_REQUESTS 


If more than one thread is setting and clearing the semaphore, a thread may 
have to wait through several changes of the semaphore before it can continue 
(depending on which thread clears the semaphore and when the system 

scheduler passes control to the thread). As long as the semaphore is set (even if - 
it has been cleared and reset since the thread originally called the function), the 
thread must wait. 


The DosSemSetWait function cannot be used to wait for a system semaphore 
that is set by another process unless the semaphore is nonexclusive. 


This example calls DosSemSetWait to set the specified RAM semaphore and 
then waits until another thread clears the semaphore. It waits for up to 5 
seconds and then returns an ERROR_SEM_TIMEOUT error value if a time-out 
occurs before the semaphore is cleared. 


#define INCL_DOSERRORS 7* include error constants */ 


ULONG hsem = O; 
if (DosSemSetWait(&hsem, SOOOL) == ERROR_SEM_TIMEOUT) { 


: /* error processing */ 
else { 


DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemClear, DosSem- 
Request, DosSemWait 
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M@ DosSemWait 


USHORT DosSemWait( hsem, /TimeOut) 
HSEM hsem; /« semaphore handle »/ 
LONG /TimeOut; /« time-out »/ 


The DosSemWait function waits for a specified semaphore to be cleared. Dos- 
SemWait waits until a thread uses the DosSemClear function to clear the sema- 
phore or until a time-out occurs. If no previous thread has set the semaphore, 
DosSemWait returns immediately. 


Parameters hsem _ \dentifies the semaphore to set. This value can be the handle of a 
system semaphore that has been previously created or opened by using the Dos- 
CreateSem or DosOpenSem function, or it can be the address of a RAM sema- 
phore. 


ITimeOut Specifies how long to wait for the semaphore to clear. If the value 
is greater then zero, this parameter specifies the number of milliseconds to wait 
before returning. If the value is SEM_IMMEDIATE_RETURN, the function 
returns immediately. If the value is SEM_INDEFINITE_WAIT, the function 
waits indefinitely. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
. value, which may be one of the following: 


ERROR_EXCL_SEM_ALREADY_OWNED 
ERROR_INTERRUPT 
ERROR_INVALID_HANDLE 
ERROR_SEM_TIMEOUT 


Comments The DosSemWait function cannot be used to wait for a system semaphore that 
is owned by another process unless the semaphore is nonexclusive. 


If more than one thread is setting and clearing the semaphore, the thread calling 
DosSemWait may have to wait through several changes of the semaphore before 
it continues (depending on which thread clears the semaphore and when the sys- 
tem scheduler passes control to the calling thread). The thread must wait for as | 
long as the semaphore is set, even if the semaphore has been cleared and reset 
since the thread originally called the function. 


Example This example calls the DosSemWait function to wait for up to 5 seconds for a 
RAM semaphore. If a time-out occurs before the semaphore handle is retrieved, 
the function returns an ERROR_SEM_TIMEOUT error value. 


ULONG hsem = O; 
if (DosSemWait(&hsem, 5000L) == ERROR_SEM_TIMEOUT) { 


: /* error processing */ 
} 
else { 


See Also DosCreateSem, DosMuxSemWait, DosOpenSem, DosSemRequest, DosSem- 
SetWait, WinMsgSemWait 
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— DosSendSignal 


USHORT DosSendSignal(idProcess, usSigNumber) 
USHORT idProcess; /« process identifier of subtree root «/ 
USHORT usSigNumber; /« signal to send »/ 


The DosSendSignal function sends a CTRL+C or CTRL+BREAK signal to the last 
descendant process that has a corresponding signal handler installed. 


Parameters idProcess Specifies the process identification code (PID) of the root process 
of the subtree. It is not necessary that this process still be running, but it is 
necessary that this process be a direct child of the process that issues this call. 


usSigNumber Specifies the signal to send. It can be SIG_LCTRLC to send a 
CTRL+C signal, or SIG_CTRLBREAK to send a CTRL+BREAK signal. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
See Also DosFlagProcess, DosHoldSignal, DosSetSigHandler 
HB DosSetCp 


USHORT DosSetCp(usCodePage, usReserved) 
USHORT usCodePage; /x code-page identifier »/ 
USHORT usReserved; ——_/« must be zero »/ 


The DosSetCp function sets the code-page identifier for the current process. 
The code-page identifier defines which translation table the system should use to 
translate input from the keyboard or to translate output to the screen and 


printer. 

Parameters usCodePage — Specifies the code-page identifier. 
usReserved Specifies a reserved value; must be zero. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. . 

Comments The file system activates the current code page for printer output whenever the 


printer is opened. 


The code-page identifier can be one of the following values: 


Number Code page 

437 United States 

850 . Multilingual 

860 Portuguese . 
863 French-Canadian 
865 Nordic 


See Also DosGetCp 
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HH DosSetDateTime 


USHORT DosSetDateTime ( pdateTime) 
PDATETIME pdateTime; /« pointer to structure for date and time «/ 


The DosSetDateTime function sets the current date and time. Although MS 
OS/2 maintains the current date and time, any process can change the date and 
time by using the DosSetDateTime function. 


The DosSetDateTime function is a family API function. 


Parameters pdateTime Points to the structure that contains the date and time informa- 
tion. The DATETIME structure has the following form: 


typedef struct _DATETIME { 
UCHAR hours; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
UCHAR day; 
UCHAR month; 
USHORT year; 
SHORT timezone; 
UCHAR weekday; 

} DATETIME; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 
ERROR_TS_DATETIME 
Example This example retrieves the current date and time and then calls the DosSetDate- 


Time function to change the month to September and the day to the 26th: 
DATETIME dateTime; 


DosGetDateTime (&dateTime) ; /* gets the current date and time */ 

dateTime.month = 9; /* changes the month */ 

dateTime.day = 26; /* changes the day */ 

DosSetDateTime (&dateTime) ; /* sets the new date and time * 
See Also DosGetDateTime 


™@ DosSetFHandState 


USHORT DosSetFHandState (hf, fsState) 
HFILE hf; /« file handle x/ 
USHORT fsState; /« file-state flags »/ 


The DosSetFHandState function modifies a file’s inheritance, fail-on-error, and 
write-through. These flags are originally set by using the DosOpen function when 
the file is opened. 


The DosSetFHandState function is a family API function. 


Parameters § hf Identifies the handle of the file to be set. This handle must have been 
created previously by using the DosOpen function. 
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Return Value 


Restrictions 


Example 


fsState Specifies the state of the file-handle. This parameter can be one or 


more of the following values: 
Value Meaning | 


OPEN_FLAGS_FAIL_ON_ERROR Any function that uses the file han- 
dle returns immediately with an 
error value if there is an I/O 
error—for example, if the drive 
door is open or a sector is missing. 
If this value is not specified, the 
system passes the error to the sys- 
tem critical-error handler, which 
then reports the error to the user 
with a hard-error popup. The fail- 
on-error flag is not inherited by 
child processes. 


The fail-on-error flag applies to all 
functions that use the file handle, 
with the exception of the Dos- 
DevIOCtl function. 


OPEN_FLAGS_NOINHERIT The file handle is not available to 
any child process started by the 
current process. If this value is not 
specified, any child process started 
by the current process can use the 
file handle. 


OPEN_FLAGS_WRITE_THROUGH This flag applies to functions, such 
as DosWrite, that write data to the 

file. If this value is specified, the 
system writes data to the device 
before the given function returns. 
Otherwise, the system may store 
the data in an internal file buffer 
and write the data to the device 
only when the buffer is full or the 
file is closed. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_HANDLE 
ERROR_INVALID_PARAMETER 


In real mode, the following restriction applies to the DosSetFHandState func- 
tion: 


— Only the OPEN_FLAGS_NOINHERIT flag can be set. 


This example opens the file abc with the inheritance flag set to zero (all child 
processes inherit the file handle). It retrieves the current file-handle state, clears 
the bits that are required to be zero, sets the inheritance flag using the OR 
operator, and calls the DosSetFHandState function. 
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HFILE hf; 
USHORT usAction, fState; 
DosQFHandState(hf, &fState) ; /* gets the current state */ 
DosSetFHandState (hf, /* handle to the file * 
(fState | OPEN _FLAGS_NOINHERIT) ); /* set noinheritance flag */ 
See Also DosBufReset, DosClose, DosDupHandle, DosExecPgm, DosOpen, DosQF- 


HandState, DosSetMode, DosWrite 


DosSetFilelnfo 

USHORT DosSetFileInfo (hf, usinfoLevel, pfstsBuf, cbBuf) 
HFILE Af; /x file handle »/ 
USHORT usinfoLevel; /« level of file information af 
PBYTE pfstsBuf; /« pointer to file-status information «/ 
USHORT cbBut; /« length of file-information buffer »/ 


The DosSetFileInfo function changes the time and date information for the 
specified file. The function replaces a file’s time and date information with the 
information given in the structure pointed to by the pfstsBuf parameter. 


The DosSetFileInfo function is a family API function. 


Parameters hf Identifies the file whose time and date information is being changed. This 
handle must have been created previously by using the DosOpen function. 


usInfoLevel Specifies the level of file information being defined. In MS OS/2, 
version 1.1, this value must be 0x0001. 


pfstsBuf Points to the FILESTATUS structure that contains the new informa- 
tion. The FILESTATUS structure has the following form: 


typedef struct _FILESTATUS { 
FDATE fdateCreation; 
ETIME ftimeCreation; 
FDATE. fdateLastAccess; 
FIIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbhFileAlloc; 

; USHORT attrFile; 

} FILESTATUS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbBuf Specifies the length in bytes of the structure pointed to by the pfstsBuf 
parameter. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_INSUFFICIENT_BUFFER 
ERROR_INVALID_FUNCTION 
ERROR_INVALID_HANDLE 
ERROR_INVALID_LEVEL 
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Comments The DosSetFileInfo function does not change information in read-only files. 
A zero in matching date and time fields will cause that aspect of file information 
to be left unchanged. For example, if both the fdateCreation and ftimeCreation 
fields are set to zero, both of these attributes are left unchanged. 

See Also DosNewSize, DosQFileInfo, DosSetFileMode 

DosSetFileMode 


USHORT DosSetFileMode ( pszFileName, usAttribute, ulReserved) 


PSZ pszFileName; 
USHORT usAttribute; 
ULONG u/Reservea; 


Parameters 


Return Value 


See Also 


/x filename »/ 
/» new file attribute «/ 
/x must be zero »/ 


The DosSetFileMode function sets the file attributes of the specified file. A file’s 
mode is defined by the settings of its attributes. 


The DosSetFileMode function is a family API function. 


pszFileName Points to a null-terminated string that specifies the name of the 
file. The string must be a valid MS OS/2 filename. 


usAttribute Specifies the file’s new attributes. This parameter can be a combi- 
nation of the following values: 


Value Meaning 

FILELNORMAL File can be read from or written to. 

FILE_LREADONLY File can be read from but not written to. 

FILE_HIDDEN File is hidden and does not appear when a directory 
is listed. 

FILE_SYSTEM File is a system file. 

FILE_ARCHIVED File has been archived. 


The FILELNORMAL value can be combined only with the FILE_LARCHIVED 
value. 


ulReserved Specifies a reserved value; must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_DRIVE_LOCKED 
ERROR_FILE_NOT_FOUND 
ERROR_NOT_DOS_DISK 
ERROR_PATH_NOT_FOUND 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_SHARING_VIOLATION 


DosQFileMode 


B DosSetFSinfo 
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USHORT DosSetFSinfo ( usDriveNumber, usinfoLevel, pbBuf, cbBuf) 
USHORT usDriveNumber; /« drive number »/ 


USHORT usinfoLevel; 


PBYTE pbBuf; 
USHORT cbBuf; 


Parameters 


Return Value 


See Also 


M@ DosSetMaxFH 


/« level of file-system information »/ 
/« pointer to structure for file-system information «/ 
/« length of buffer for file-system information »/ 


The DosSetFSInfo function sets information for a file-system device. 
The DosSetFSInfo function is a family API function. 


usDriveNumber Specifies the logical drive number. The usDriveNumber 
parameter must be a value from 0 through 26. The default drive is 0, drive A is 
1, drive B is 2, and so on. 


usInfoLevel Specifies the level of file information required. In MS OS/2, ver- 
sion 1.1, this value must be 0x0002. 


pbBuf Points to the structure that receives the information. When the request 
is for level-2 file information, this parameter points to a structure that contains 
the volume-label information. The VOLUMELABEL structure has the following 
form: 
typedef struct _VOLUMELABEL { 

BYTE cch; 


CHAR achVolLabel [12]; 
} VOLUMELABEL; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


cbBuf Specifies the length (in bytes) of the VOLUMELABEL structure 
pointed to by the pbBuf parameter. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_CANNOT_MAKE 
ERROR_INSUFFICIENT_BUFFER 
ERROR_INVALID_DRIVE 
ERROR_INVALID_LEVEL 
ERROR_INVALID_NAME 
ERROR_LABEL_TOO_LONG 


DosQCurDisk, DosQFSInfo 


USHORT DosSetMaxFH(usHandles) 


USHORT usHandles; 


/« number of file handles «/ 


The DosSetMaxFH function sets the maximum number of file handles for the 
current process. The number of available handles limits the number of files that 
can be opened at once. However, all handles are not always available for use by 
the process. When determining the required number of handles, add several for 
the dynamic-link modules (these modules use several handles) and three for the 
default system input/output handles. 
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Parameters usHandles Specifies the maximum number of file handles provided to the call- 
ing process. The maximum value for this parameter is 255; the default is 20. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_LINVALID_PARAMETER 
ERROR_NOT_ENOUGH_MEMORY 


Comments This function preserves all currently open file handles. 
See Also DosDupHandle, DosOpen 


DosSetNmPHandState 


USHORT DosSetNmPHandState (hp, fsState) 
HPIPE hp; /« pipe handie «/ 
USHORT fsState; /« state flag «/ 


The DosSetNmPHandState function is used to set the read mode and the block- 
ing mode of a named pipe. 


‘Parameters hp Identifies the pipe to read from. 


fsState Specifies the new mode. The mode is a combination of a read-mode 
flag and a wait flag. The possible values are: 


Value 7 Meaning 

PIPELREADMODE_BYTE Read pipe as a byte stream. 

PIPELREADMODE_MESSAGE Read pipe as a message stream. 

PIPE_LNOWAIT Reading from and writing to the pipe 
returns immediately if no data is avail- 
able. 

PIPE_WAIT 


Reading from and writing to the pipe 
waits if no data is available. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_INVALID_PARAMETER 
ERROR_PIPE_NOT_CONNECTED 


See Also DosQNmPHandState 
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HZ DosSetNmPipeSem 


USHORT DosSetNmPipeSem (hp, hsem, usKeyVa/) 
HPIPE hp; /« pipe handle »/ 
HSEM hsem; /« semaphore handle _ «/ 
USHORT usKeyVal; /« key value to associate «/ 


The DosSetNmPipeSem function associates a semaphore with a named pipe. 


Parameters hp Identifies the named pipe. 
hsem Identifies the semaphore to associate with the pipe. 
usKeyVal . Specifies a key identifier to associate with the named pipe. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_FUNCTION 
ERROR_PIPE_NOT_CONNECTED 
ERROR_SEM_NOT_FOUND 


Comments Up to two semaphores can be attached to a named pipe; one for the serving end 
of the pipe and one for the client end of the pipe. If a semaphore is already 
attached to one end of the named pipe, the old semaphore will be overwritten. 


The DosSetNmPipeSem function only returns successfully for local named pipes. 
If the DosSetNmPipeSem function attempts to associate a semaphore with a 
remote named pipe, an ERROR_INVALID_FUNCTION error value is returned 
by the DosSetNmPipeSem function. | 


The DosSetNmPipeSem function allows a serving application that needs to han- 
die a large number of incoming named pipes to avoid dedicating a thread for 
each named pipe and avoid polling the pipes. An application can instead call the 
DosSemWait or DosMuxSemWait function to determine when I/O can be per- 
formed on the pipe semaphore(s). This allows a large number of named pipes to 
be handled in an event-driven way, using only a small number of threads. The 

-DosQNmPipeSemState function can be used to provide additional information 
about what I/O can be performed on the set of pipes. 


See Also DosMuxSemWait, DosQNmPipeSemState, DosSemWait 


—M DosSetProcCp 


USHORT DosSetProcCp(usCodePage, usReserved) 
USHORT usCodePage; /« code-page identifier »/ 
USHORT usReserved; /« must be zero «/ 


The DosSetProcCp function allows a process to set its code page. 


Parameters usCodePage Specifies a code-page-identifier word that has one of the follow- 
ing values: 
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Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian 
865 Nordic 


usReserved Specifies a reserved value; must be zero. 


This function sets the process code page of the calling process. The code page 


of a process is used in three ways. First, the printer code page is set to the pro- 
cess code page through the file system and Printer spooler (the system spooler 
must be installed) when the process makes a request to open the printer. Calling 
DosSetProcCp does not affect the code page of a printer opened before the call, 
nor does it affect the code page of a printer opened by another process. Second, 
country-dependent information will, by default, be retrieved encoded in the code 
page of the calling process. Third, a newly created process inherits its process 


DosSetProcCp does not affect the screen or keyboard code page. 


Comments 

code page from its parent process. 
See Also DosSetCp 
DosSetPrty 


USHORT DosSetPrty (fScope, fPrtyClass, sChange, id) 
USHORT fScope; /» indicates the scope of change «/ 


The DosSetPrty function sets the scheduling priority of the specified process or 
thread by changing the priority class and/or the priority level. 


Within each class, a thread’s priority level may vary—either through system 
action or through the DosSetPrty function. The system changes a thread’s prior- 
ity levels based on that thread’s actions and the overall system activity. 


USHORT fPrtyClass; /« priority class to set »/ 
SHORT sChange; /»« change in priority level »/ 
USHORT id; /» process or thread identifier —«/ 
Parameters fScope 
following values: 
Value 


PRTYS_PROCESS 
PRTYS_PROCESSTREE 


PRTYS_THREAD 


Specifies the scope of the request. This parameter can be one of the 


Meaning 
Priority for the process and all its threads. 


Priority for the process and all child pro- 
cesses. 


Priority for one thread in the current process. 
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fPrtyClass Specifies the priority class of a process or thread. This parameter 
can be one of the following values: 


Value Meaning 
PRTYC_IDLETIME Idle-time. 
PRTYC_NOCHANGE No change; leave as is. 
PRTYC_REGULAR Regular. 
PRTYC_TIMECRITICAL Time-critical. 


sChange Specifies the relative change in the current priority level of the pro- 
cess or thread. This parameter can be any value from - 31 through +31, or the 
constants PRTYD_MINIMUM or PRTYD_MAXIMUM, which specify the 
minimum and maximum change allowed. 


id Specifies a process or thread identifier, depending on the value of the 
fScope parameter. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_PCLASS 
ERROR_LINVALID_PDELTA 
ERROR_INVALID_PROCID 
ERROR_INVALID_SCOPE 
ERROR_INVALID_THREADID 
ERROR_NOT_DESCENDANT 


See Also DosEnterCritSec, DosGetInfoSeg, DosGetPrty 
DosSetSession 

USHORT DosSetSession(idSession, pstsdata) . 

USHORT idSession; /»« session identifier »/ 


PSTATUSDATA pstsdata; /» prior to structure for session-status data «/ 


The DosSetSession function sets the status of a child session. 


Parameters idSession Specifies the identifier of the session for which the status is set. 
This identifier must have been created previously by using the DosStartSession 
function. | 


pstsdata Points to a STATUSDATA structure that contains the session-status 
data. The STATUSDATA structure has the following form: 


typedef struct _STATUSDATA { 
USHORT Length; 
USHORT SelectInd; 
USHORT BindInd; 

} STATUSDATA; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
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Comments 


See Also 


The DosSetSession function allows a parent session to use the SelectInd and 
BindInd fields of the STATUSDATA structure to specify whether the child ses- 
sion can be selected by the user and whether or not the child session will also be 
brought to the foreground when the user brings the parent session to the fore- 
ground. These fields affect selections made by the user from the switch list; they 
do not affect selections made by the parent session. Each of these fields can be 
set individually, without affecting the current setting of the other. 


A parent session can call the DosSetSession function only for a child session; 
neither the parent session itself nor any second-level child session can be set by 
using this function. The DosSetSession function can change the status of a child 
session only if that child was started as a related session; DosSetSession cannot 
change the status of sessions that were started as independent sessions. 


A bond between a parent session and a child session can be broken by calling 
the DosSetSession function and specifying either BindInd = 2 to break the bond, 
or BindInd = 1 to break the bond and establish a new bond with a different child 
session. 


A child session that is bound to a parent session will be brought to the fore-. 
ground when the user selects the parent session, even if the status of the child 
session is nonselectable. If there is a bond between a parent session and a child 
session, and another bond between that child and a second-level child session, 
the second-level child session will be brought to the foreground when the user 
selects the parent session. 


A parent session may be running in either the foreground or the backeroand 
when DosSetSession is called. 


The DosSetSession function may be called only by the process that started the 
session identified by the idSession parameter. 


DosSelectSession, DosStartSession, DosStopSession 


DosSetSigHandler 


USHORT DosSetSigHandler( pfnSigHandiler, pfnPrev, pfAction, fAction, usSigNumber) 
PFNSIGHANDLER pfnSigHandler; /» pointer to signal-handler function »/ 
PFNSIGHANDLER FAR * pfnPrev; /« pointer to previous handler address »/ 


PUSHORT pfAction; 


USHORT fAction; 


/» pointer to variable for previous handler action «/ 
/« type of request »/ 


USHORT usSigNumber; /» signal number »/ 


Parameters 


The DosSetSigHandler function installs or removes a signal handler for a 
specified signal. This function can also be used to ignore a signal or install a 
default action for a signal. 


The DosSetSigHandler function is a family API function. 
pfnSigHandler Points to the address of the signal-handler function that 


receives control when a given signal occurs. For a full description, see the fol- 
lowing “Comments” section. 


pfnPrev Points to the variable that receives the address of the previous signal 
handler. 


Return Value 


Comments 
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pfAction Points to the variable that receives the value of the previous signal 
handler’s fAction parameter. The pfAction parameter can be a value from 0 
through 3. 


fAction Specifies the type of request. This parameter can be one of the fol- 
lowing values: 
Value Meaning 


SIGA_ACCEPT The signal handler specified in the pfnSigHandler 
parameter will accept the signal specified in the 
usSigNumber parameter. 


SIGA_ACKNOWLEDGE The signal specified in the usSigNumber parameter 
is acknowledged. The signal handler specified in 
the pfnSigHandler parameter will accept the signal. 


SIGA_ERROR It is an error for any other process to signal this 
process with the signal specified in the usSig- 
Number parameter. 


SIGA_IGNORE Ignore the signal. 
SIGA_KILL Remove the signal handler. 


usSigNumber Specifies the signal number. This parameter can be one of the 
following values: 


Value Meaning 

SIG_BROKENPIPE Connection to a pipe was broken. 
SIG_CTRLBREAK CTRL+BREAK. 

SIG_CTRLC CTRL+C. 

SIG_KILLPROCESS Program terminated. 
SIG_PFLG_A Process flag A. 

SIG_PFLG_B Process flag B. 

SIG_PFLG_C Process flag C. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_INVALID_FUNCTION 
ERROR_INVALID_SIGNAL_NUMBER 


The DosSetSigHandler function installs the signal handler that the system will 
call whenever the corresponding signal occurs. The signal handler is a function 
that responds to a signal by carrying out tasks (such as cleaning up files). A sig- 
nal is an action initiated by the user or another process that temporarily 
suspends execution of the process while the signal is processed. Signals occur 
when the user presses the CTRL+C or CTRL+BREAK key sequences, when the pro- 
cess ends, or when another process calls the DosFlagProcess function. By 
default, the CTRL+C, CTRL+BREAK, and end-of-process signals terminate the pro- 
cess. 
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Restrictions 


See Also 


The signal-handler function can use the address and fAction parameter value of 
the previous signal handler to pass the signal through a chain of previous signal 
handlers. The new signal handler can also use the previous address and fAction 
value to restore the previous handler. 


The DosSetSigHandler function acknowledges a signal and reenables it for sub- 
sequent input if the fAction parameter is set to SIGA_ACKNOWLEDGE. A 
process must acknowledge the signal while processing it to permit the signal to 
be used again. . . 

The signal handler has the following form: 


VOID PASCAL FAR FuncName(usSigArg, usSigNum) 


USHORT usSigArg; /* furnished by DosFlagProcess if appropriate *7 
USHORT usSigNum; /* signal number being processed a/ 
{ . 

return; 
} 

Parameters Description 

usSigArg Specifies the signal argument passed by the process that sends 


the process-flag signal. 


usSigNum Specifies the signal number. This parameter can be any of the 
values listed for the usSigNumber parameter of the DosSet- 
SigHandler function. 


When a signal occurs, the system calls the corresponding signal handler, which 
then carries out tasks, such as displaying a message and writing and closing files. 
The signal handler receives control under the first thread of a process (thread 1). 
The thread that was executing when the signal occurred waits for signal process- 
ing to be completed. The signal handler can use the return statement to return 
control and restore execution of the waiting thread or the DosExit function to 
terminate the process. 


The signal handler is not suspended when the DosEnterCritSec function is 
called. If a signal occurs, the processing done by the signal handler must not 
interfere with the processing that is done by the thread calling the DosEnter- 
CritSec function. 


All registers other than cs, ip, ss, sp, and flags in assembly-language signal 
handlers contain the same values as when the signal was received. The signal 
handler may exit by executing a far return instruction; execution resumes where 
it was interrupted, and all registers are restored to their values at the time of the 
interruption. 


In real mode, the following restriction applies to the DosSetSigHandler function: 


m Only the signal-break (SIG_CTRLBREAK) and signal-interrupt 
(SIG_CTRLC) signals are available. DosSetSigHandler may be used to 
install signal handlers for only these two signals. 


DosCreateThread, DosFlagProcess, DosHoldSignal 


HM DosSetVec 
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USHORT DosSetVec(usVecNum, pfnFunction, ppfnPrev) 


USHORT usVecNum; 
PFN pfnFunction; 
PPEN ppfnPrev; 


Parameters 


Return Value 


Comments 


/« type of exception »/ 
/x pointer to function x/ 
/« pointer to variable for previous function’s address «/ 


The DosSetVec function installs or removes an exception handler for a specified 
exception. An exception is a program error, such as division by zero, that causes 
the system to pass control to the exception handler. The exception handler is an 
assembly-language routine that corrects errors or cleans up programs before ter- 
minating. The system calls the exception handler whenever the specified excep- 
tion occurs. If a process does not install its own exception handler, the default 
exception handler terminates the process when an exception occurs. 


The DosSetVec function is a family API function. 


usVecNum Specifies the number of the exception vector. This parameter can 
be one of the following values: 


Value Meaning 
VECTOR_DIVIDE_BY_ZERO Division by zero 
VECTOR_EXTENSION_ERROR Processor extension error 
VECTOR_INVALIDOPCODE Invalid opcode 
VECTOR_NO_EXTENSION Processor extension not available 
VECTOR_OUTOFBOUNDS Out of bounds 
VECTOR_OVERFLOW Overflow 


pfnFunction Points to the address of the exception handler that receives con- 
trol when the specified exception occurs. If this parameter is zero, the DosSet- 

Vec function removes the current exception handler. For a full description, see 

the following “Comments” section. 


ppfnPrev Points to the variable that receives the address of the previous 
exception handler. The new exception handler can use this address to chain 
exception handling through all previous handlers or to restore the previous 
exception handler. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_FUNCTION 


When the system calls the exception handler, interrupts are enabled and the 
machine status word and far return address are pushed on the stack. If the 
exception handler returns, it must use the iret (return from interrupt) instruc- 
tion. 


If the DosSetVec function is used to install an exception handler for vector 
VECTOR_EXTENSION_ERROR (processor extension not available), the func- 
tion sets the machine status word (MSW) to indicate that no 80287 is available. 
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Restrictions 


See Also 


DosSetVerify 


The emulate bit is set and the monitor processor bit is cleared. (This is done 
without regard for the true state of the hardware.) If the DosSetVee function is 
used to remove the exception handler for VECTOR_EXTENSION_ERROR, 
the function sets the machine status word to reflect the true state of the 
hardware. 


In real mode, the following restriction applies to the DosSetVec function: 


@ Since the 8086 amd 8088 microprocessors do not raise this exception, 
usVecNum may not be VECTOR_EXTENSION_ERROR. 


DosDevConfig, DosError 


USHORT DosSetVerify ( fVerify) 


USHORT fVerify; 


Parameters 


Return Value 


Comments 


See Also 


DosSizeSeg 


/ verify on/off »/ 


The DosSetVerify function enables or disables data verification. When 
verification is enabled, the system verifies that data is written correctly whenever 
a process writes to a disk file. 


The DosSetVerify function is a family API function. 


{Verify Specifies whether data verification is enabled. If the {Verify parameter 
is TRUE, verification is enabled. If it is FALSE, verification is disabled. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_VERIFY_S WITCH 


Errors when writing to a disk file are very rare. This DosSetVerify function 
allows a process to verify the proper recording of critical data. 


DosQVerify 


USHORT DosSizeSeg(se/, pu/Size) 


SEL sel; 
PULONG pul/Size; 


Parameters 


/« segment selector a/ 
/« receives segment size »/ 


The DosSizeSeg function retrieves the size (in bytes) of a specified segment. 
The DosSizeSeg function is a family API function. 


sel Specifies the selector of the segment. For huge segments, this must be the 
base selector. 


Return Value 


See Also 


DosSleep 
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pulSize Points to the variable that receives the segment size (in bytes). (For 
huge segments, the number of full segments will be in the high word, and the 
size of the last segment will be in the low word. These values are equivalent to 
the values of the usNumSeg and usPartialSeg parameters that were passed to the 
DosAllocHuge or DosReallocHuge function.) 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


DosAllocHuge, DosAllocSeg, DosReallocHuge 


USHORT DosSleep(u/Time) 


ULONG ulTime; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/« number of milliseconds to wait «/ 


The DosSleep function causes the current thread to wait for a specified interval 
or, if the specified interval is zero, to give up the remainder of the current time 
slice. 


The DosSleep function is a family API function. 


ulTime Specifies the number of milliseconds that the thread waits. This value 
is rounded up to the next clock tick. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_TS_WAKEUP 


The time the thread waits can be different from the specified time by a clock tick 
or two, depending on the execution status of the other threads running in the 
system. If the specified interval is zero, the process forgoes the remainder of its 
CPU time slice but is scheduled normally for its next time slice. When a process 
continues after suspension, its scheduled execution time could be delayed by 
hardware interrupts or by another thread running at a higher priority. If the time 
interval is not zero it is given in milliseconds, which are rounded up to the reso- 
lution of the scheduler clock. The DosSleep function should not be substituted 
for a real-time clock, because the rounding of the wait interval will cause inaccu- 
racies to accumulate. 


This example sets up a loop that waits for one second and then retrieves the 
time and date: 


DATETIME date; 


for (;; 
DosSleep (1000L) ; /* waits for one second * 
DosGetDateTime (&date) ; /* retrieves the time and date */ 
} 


DosGetInfoSeg, DosTimerAsync, DosTimerStart 
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HM DosStartSession 


-USHORT DosStartSession( pstdata, pidSession, ppid) 
PSTARTDATA psidata; /« pointer to structure containing session data «/ 
PUSHORT pidSession; /« pointer to variable for session identifier »/ 
PUSHORT ppia; /« pointer to variable for process identifier —— «/ 


The DosStartSession function starts a session (screen group) and specifies the 
name of the program to start in that session. This function creates either an 
independent session or a child session, depending on the value of the Related 
field in the STARTDATA structure. 


Parameters pstdata Points to the STARTDATA structure that contains data describing the 
session to start. The STARTDATA structure has the following form: 


typedef struct _STARTIDATA { 
USHORT Length; 
USHORT Related; 
USHORT FgBg; 
USHORT TraceOpt; 
PSZ PgmTitle; 
PSZ PgmName; 
PBYTE PgmInputs; 
PBYTE TermQ; 
PBYTE Environment; 
USHORT InheritOpt; 
USHORT SessionType; 
PSZ IconFile; 
ULONG PgmHandle; 
USHORT PgmControl; 
USHORT InitXPos; 
USHORT InitYPos; 
USHORT InitXSize; 

USHORT InitYSize; 

} STARTDATA; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
pidSession Points to the variable that receives the identifier of the child ses- 


sion. 
ppid Points to the variable that receives the process identifier of the child pro- 
cess. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

Comments The MS OS/2 session manager writes a data element into the specified queue 


when the child session created by the DosStartSession function terminates. A 
parent session can be notified when a child session has terminated by using the 
DosReadQueue function. When the child session terminates, the request value 
returned by DosReadQueue is zero, and the data-element format consists of two 
unsigned values: the session identifier and the result code. . 


Only the process that calls the DosStartSession function should call the Dos- 
ReadQueue function. Only this process can address the notification data ele- 
ment. After reading and processing the data element, the calling process must 
use. the DosFreeSeg function to free the segment that contains the data element. 


A child session is created when the Related field of the STARTDATA structure 
is set to TRUE. The process identifier of the child process cannot be used with 
MS OS/2 functions, such as DosSetPrty, that require a parent process/child pro- 
cess relationship. 
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An independent session is created when the Related field of the STARTDATA 
structure is set to TRUE. An independent session is not under the control of the 
starting session. The DosStartSession function does not copy session and pro- 
cess identifiers for an independent session to the pidSession and ppid parame- 
ters. 


New sessions can be started in the foreground only when the caller’s session (or 
one of the caller’s descendant sessions) is currently executing in the foreground. 
The new session appears in the shell switch list. 


See Also DosCreateQueue, DosExecPgm, DosFreeSeg, DosReadQueue, DosSelect- 
Session, DosSetSession, DosStopSession 


DosStopSession 

USHORT DosStopSession (fScope, idSession, ulReserved) 
USHORT fScope; /« all sessions/specified session stopped «/ 
USHORT idSession; /« session identifier »/ 
ULONG u/Reserved; /« must be zero »/ 


The DosStopSession function terminates a session that was started by using the 
DosStartSession function. 


Parameters fScope Specifies whether the function stops all sessions or only the specified 
session. If the fScope parameter is 0x0000, the function stops only the specified 
session. If it is 0x0001, the function stops all sessions. 


idSession Specifies the identifier of the session to be stopped. This identifier 
must have been created previously by using the DosStartSession function. This 
parameter is ignored if the fScope parameter is set to 0x0001. 


ulReserved Specifies a reserved value; must be zero. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments _ The DosStopSession function can terminate only child sessions that were started 


by using the DosStartSession function (child sessions of the terminated session 
will terminate as well). Sessions that were started as independent sessions cannot 
be terminated by using DosStopSession. 


A parent session can be running in either the foreground or the background 
when DosStopSession is issued. If a child session is in the foreground when it is 
stopped, the parent session becomes the foreground session. The DosStopSes- 
sion function breaks any bond between the parent session and the specified child 
session. 


A process running in the session specified by the idSession parameter can refuse 
to terminate. If this happens, DosStopSession returns zero. To verify that the 
target session has terminated, a process can wait for notification through the ter- 
mination queue that is specified in the DosStartSession function. 


See Also DosSetSession, DosStartSession 
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™ DosSubAlloc _ 
USHORT DosSubAlloc(se/, pusOffset, cbBlock) 


SEL sel; /« segment selector »/ 
PUSHORT pusOffset; /« pointer to variable for offset »/ 
USHORT cbBiock; /+ number of bytes of requested memory «/ 


The DosSubAlloc function allocates memory in a segment that was allocated 
previously by using the DosAllocSeg or DosAllocShrSeg function and hat was 
initialized by using the DosSubSet function. 


The DosSubAlloc function i is a family API function. 
Parameters sel Specifies the selector of the data segment in which the memory suouid be 
allocated. 
pusOffset Points to the variable that receives the offset to pale allocated block. 
cbBlock Specifies the size (in bytes) of the requested memory block. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_NOMEM 


Comments The cbBlock parameter must not be greater than the maximum size of the seg- 
ment minus 8 bytes. Since all memory blocks are aligned on byte boundaries, the 
cbBlock parameter does not need to be a multiple of 16. 


See Also DosAllocSeg, DosAllocShrSeg, DosSubFree, DosSubSet 


@ DosSubFree 


USHORT DosSubFree (sel, offBiock, cbBlock) 

SEL sel; /x segment selector »/ 
USHORT offBlock; /« block offset »/ 
USHORT cbBiock; /« number of bytes in block to free »/ 


The DosSubFree function frees memory that was allocated previously by using . 
the DosSubAlloc function. | 


The DosSubFree function i is a family API function. 
Parameters sel Specifies the selector of the data segment from which the memory should 
. be freed. 


offBlock Specifies the offset of the memory block to be freed. This offset 
must have been created previously by using the DosSubAlloc function. 


cbBlock Specifies the size (in bytes) of the block to free. 


Return Value 


See Also 


DosSubSet 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_OVERLAP 


DosAllocSeg, DosSubAlloc, DosSubSet 


USHORT DosSubSet (sel, fFiags, cbSeg) 


SEL sei; 
USHORT fFiags; 
USHORT cbSeg; 


Parameters 


Return Value 


Comments 


See Also 


/x segment selector x/ 
/« initialize/increase size of segment «/ 
/« new size of block x/ 


The DosSubSet function initializes a segment for suballocation or changes the 
size of a previously initialized segment. 


The DosSubSet function is a family API function. 


sel Specifies the selector of the data segment. 


fFlags Specifies whether to initialize the segment or increase its size. If the 
fFlags parameter is 0x0001, the function initializes the segment. If fFlags is 
0x0000, the function changes the size of the segment. 


cbSeg Specifies the new size (in bytes) of the segment. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_DOSSUB_BADFLAG 
ERROR_DOSSUB_BADSIZE 
ERROR_DOSSUB_SHRINK 


If the fFlags parameter is 0x0001, the DosSubSet function initializes the segment 
so that the DosSubAlloc function can be used to allocate memory blocks in the 
segment. The segment must have been allocated previously by using the Dos- 
AllocSeg or DosAllocShrSeg function. 


If the fFlags parameter is 0x0000, the DosSubSet function changes the size of 
the segment to the number of bytes specified by the cbSeg parameter. If the 
specified size is greater than the current size of the segment, the DosReallocSeg 
function must be called before DosSubSet. If DosSubSet is not called after 
changing the size of a segment by using DosReallocSeg, the results can be 
unpredictable. 


When changing the size of a segment by using the DosSubSet function, the cbSeg 
parameter must be a multiple of 4 bytes that is greater than or equal to 12 bytes, 
or it must be zero. Otherwise, the size is rounded up to the next multiple of 4. 
In the DosSubSet function, setting the cbSeg parameter to zero indicates that the 
segment is 64K, but in the DosSubAlloc and DosSubFree functions, it is an 
error when the cbSeg parameter is equal to zero. 


DosAllocSeg, DosAllocShrSeg, DosReallocSeg, DosSubAlloc, DosSubFree 
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m™ DosSuspendThread 


USHORT DosSuspendThread( tid) 
TID tid; —_/x identifier of thread to suspend «/ 


Parameters 
Return Value 


Comments 


See Also 


DosTimerAsync 


The DosSuspendThread function suspends the execution of a thread until a call 
to the DosResumeThread function i is made that specifies the suspended thread’s 
identifier. 


tid Specifies the thread identifier of the thread to be suspended. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_INVALID_ THREADID 


The specified thread may not be aieeene immediately if it has called a system 
function that has locked some system resources; the locked resources must be 
freed before the thread is suspended. The thread will not continue to execute 
until a DosResumeThread function is called. 


A thread can suspend threads only within its process. 


DosCreateThread, DosEnterCritSec, DosResumeThread 


USHORT DosTimerAsync(u/Time, hsem, phtimer) 


ULONG u/Time; 
HSEM hsem; 
PHTIMER phtimer,; 


Parameters 


Return Value 


Comments 


/« time before semaphore is cleared = +/ 
| system-semaphore handle »/ 
7» pointer to variable for timer handle «/ 


The DosTimerAsync function creates a timer that counts for a specified number 
of milliseconds, then clears a specified semaphore. 


ulTime Specifies the time (in milliseconds) before the semaphore is cleared. 
This value is rounded up to the next clock tick, if necessary. — 


hsem Identifies the system semaphore that signals the end of the timer. This 
handle must have been created previously by using the DosCreateSem function. 


phtimer Points to the variable that receives the timer handle. 


The return value i is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


_ ERROR_TS_NOTIMER 
ERROR_TS_SEMHANDLE 


The timer runs asynchronously—that is, while the timer counts the time, the 
DosTimerAsynce function returns to let the process continue to execute other 
tasks. The timer counts the time only once. ; 


The given. semaphore must be a system semaphore. If the process uses the sema- 
phore to determine when data is available, it must use the DosSemSet function 
to set the semaphore before calling the DosTimerAsync function. 
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The timer handle specified by the phtimer parameter can be used by the Dos- 
TimerStop function to cancel the timer. 


The DosTimerAsync function is similar to the DosSleep function except that 
DosTimerAsync returns immediately; DosSleep returns only after the specified 
time has elapsed. 


See Also DosSemSet, DosSleep, DosTimerStart, DosTimerStop 


DosTimerStart 


USHORT DosTimerStart(u/Time, hsem, phtimer) 

ULONG ulTime; /« time before semaphore is cleared «/ 
HSEM hsem; /« system-semaphore handle «/ 
PHTIMER phtimer,; /« pointer to variable for timer handle «/ 


The DosTimerStart function creates a timer that counts for a specified number 
of milliseconds, then clears the specified semaphore. The function repeats this 
process continually, counting the time and clearing the semaphore, until the pro- 
cess stops it by using the DosTimerStop function. The timer handle is used in 
the DosTimerStop function to cancel the timer. 


Parameters ulTime Specifies the time (in milliseconds) before the semaphore is cleared. 


hsem Identifies the system semaphore that signals the end of the timer. This 
handle must have been created previously by using the DosCreateSem function. 


phtimer Points to the variable that receives the timer handle. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_TS_NOTIMER 
ERROR_TS_SEMHANDLE 


Comments The timer runs asynchronously—that is, while the timer counts the time, the 
function returns to let the process continue to execute other tasks. 


The given semaphore must be a system semaphore. If the process uses the sema- 
phore to determine when data is available, it must use the DosSemSet function 
to set the semaphore before calling the DosTimerStart function. 


If necessary, the DosTimerStart function rounds up the ulTime parameter to the 
next clock tick. E 


The timer may clear the semaphore several times before a process that is waiting 
for the semaphore resumes execution. If the process requires an accurate count 
of the time it waited, it should retrieve the current system time from the global 
information segment before and after waiting for the semaphore and compare 
these times. 


See Also DosGetInfoSeg, DosSemSet, DosTimerStop © 
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—™ DosTimerStop 


USHORT DosTimerStop(htimer) 
HTIMER htimer, /« timer handle «/ 


Parameters 


Return Value 


Comments 


See Also 


The DosTimerStop function stops a specified timer. 


htimer Identifies the timer to be stopped. This handle must have been created 
previously by using the DosTimerAsyne or DosTimerStart function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_TS_HANDLE 
When the DosTimerStop function stops a timer, it does not clear the corre- 
sponding semaphore. If a process is waiting for the semaphore to clear, the pro- 
cess that stops the timer should also clear the semaphore. 


DosTimerAsync, DosTimerStart 


@ DosTransactNmPipe 
USHORT DosTransactNmPipe (hp, pbOutBuf, cbOutBuf, pbinBuf, cbinBuf, pcbRead) 


HPIPE hp; 

PBYTE pbOutBuf; 
USHORT cbOutButf; 
PBYTE pbinBuf; 
USHORT cbinBuf: 
PUSHORT pcbReaa; 


Parameters 


Return Value 


/« pipe handle »/ 
/x pointer to buffer containing data x/ 
/»« number of bytes in output buffer sf 
/« pointer to buffer receiving data x/ 
/» number of bytes in input buffer »/ 


/« pointer to variable receiving number of bytes read »/ 


The DosTransactNmPipe function writes data to and reads data from a named 

pipe. 

hp Identifies the named pipe. 

pbOutBuf Points to the buffer containing the data that is written to the pipe. 

cbOutBuf Specifies the size (in bytes) of the output buffer. 

pbInBuf Points to the input buffer that receives the data read from the pipe. 

cbInBuf Specifies the size (in bytes) of the input buffer. 

Pees Points to the variable that receives the number of bytes read from 
e pipe. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_INTERRUPT 
ERROR_INVALID_FUNCTION 
ERROR_SEM_TIMEOUT 
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Comments The DosTransactNmPipe function fails if the named pipe contains any unread 
data or if the named pipe is not in message mode. A named pipe’s blocking state 
has no effect on the DosTransactNmPipe function. The DosTransactNmPipe 
function does not return until data is written into the output buffer. 


See Also DosCallNmPipe 


DosUnlockSeg 
USHORT DosUnlockSeg(se/) 
SEL sel; /« selector of segment to unlock s/ 


The DosUnlockSeg function unlocks a discardable segment. Once a segment is 
unlocked, the system may discard it to make space available for other segments. 


Parameters sel Specifies the selector of the segment to unlock. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

Comments DosUnlockSeg applies only to segments that are allocated by using the Dos- 


AllocSeg function with the fsAlloc parameter set to SEG_DISCARDABLE. 


The DosLockSeg and DosUnlockSeg functions may be nested. If DosLockSeg is 
called 5 times to lock a segment, DosUnlockSeg must be called 5 times to 
unlock the segment. A segment becomes permanently locked if it is locked 255 
times without being unlocked. 


See Also DosAllocSeg, DosLockSeg 


DosWaitNmPipe 


USHORT DosWaitNmPipe(pszName, u/TimeOut) 
PSZ pszName; /« pointer to pipe name «/ 
ULONG u/lTimeOut; _—/s timeout value af 


The DosWaitNmPipe function waits for a named pipe to become available. 
Parameters pszName_ Points to the name of the pipe. The name is in the form \pipe\name 

for a local pipe and \\server\pipe\name for a remote pipe. 

ulTimeOut Specifies a value (in milliseconds) that is the amount of time MS 

OS/2 should wait for the pipe to become available. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_BAD_PIPE 
ERROR_INTERRUPT 
ERROR_SEM_TIMEOUT 
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Comments 


See Also 


DosWrite 


The DosWaitNmPipe function should be used only when the DosOpen function 
returns the ERROR_PIPE_BUSY error value. 


If more than one process has requested a named pipe that has become available, 
the system gives the pipe to the process that has been waiting the longest. 


DosOpen 


USHORT DosWrite (hf, pvBuf, cbBuf, pcbBytesWritten) 


HFILE hf; 
PVOID pvBuf; 
USHORT cbBuf; 


/x file handle »/ 
/« pointer to buffer »/ 
/« number of bytes to write x/ 


PUSHORT pcbBytesWritten: /« pointer to variable receiving byte count «/ 


Parameters 


Return Value 


Comments 


The DosWrite function writes data from a buffer to a file, then copies the num- 
ber of bytes written to a variable. 


The DosWrite function is a family API function. 


hf Identifies the file that receives the data. This handle must have been created 
previously by using the DosOpen function. 


pvBuf Points to the buffer that contains the data to write. 
cbBuf Specifies the number of bytes to write. 
pebBytesWritten Points to the variable receiving the number of bytes written. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_INVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NOT_DOS_DISK 
ERROR_WRITE_FAULT 


The DosWrite function begins to write at the current file-pointer position. The 
file-pointer position can be changed by using the DosChgFilePtr function. 


If the specified file has been opened using the write-through flag, the Dos Write 
function writes data to the disk before returning. Otherwise, the system collects 
the data in an internal file buffer and writes the data to the disk only when the 
buffer is full. 


The DosWrite function may write fewer bytes to the file than the number 
specified in the cbBuf parameter if there is not enough space on the disk for all 
of the requested bytes. The cbBuf parameter can be zero without causing an 
error—that is, writing no bytes is acceptable. 


The efficiency with which the DosWrite function writes to a disk is improved 
when the cbBuf parameter is set to a multiple of the disk’s bytes-per-sector size. 
When cbBuf is set this way, the function writes directly to the disk, without first 
copying the data to an internal file buffer. (The DosQFSInfo function retrieves 
the byters-per-sector value for a disk.) 
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Example This example creates the file abc and calls the DosWrite function to write the 
contents of the abBuf buffer to the file: 


BYTE abBuf[512]; 

HFILE hf; 

USHORT usAction, cbBytesWritten, usError; 

usError = DosOpen("abc", &hf, G&usAction, OL, FILE_NORMAL, 
FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, OL); 

if (tusError) { 


DosWr ite (hf, /* file handle */ 

abBuf, /* buffer address a/ 
sizeof (abBuf), /* buffer size 
&cbBytesWritten) ; /* address of bytes written */ 

See Also DosChgFilePtr, DosOpen, DosRead, DosWriteAsync 

DosWriteAsync 

USHORT DosWriteAsyne (hf, hsemRam, pusErrCode, pvBuf, cbBuf, pcbBytesWritten) 

HFILE hf; /« file handle »/ 

PULONG hsemRam; /» pointer to RAM semaphore »/ 

PUSHORT pusErrCode; /« pointer to variable for error value »/ 

PVOID pvBuf; — /» pointer to buffer containing data to write «/ 

USHORT cbBuf; /« number of bytes in buffer »/ 

PUSHORT pcbBytesWritten; /» pointer to variable for bytes written x/ 


The DosWriteAsync function writes one or more bytes of data to a specified file. 
The function writes the data asynchronously—that is, the function returns 
immediately, but continues to copy data to the specified file while the process 
continues with other tasks. 


Parameters hf Identifies the file that receives the data. This handle must have been created 
previously by using the DosOpen function. 


hsemRam Points to the RAM semaphore that indicates when the function has 
finished reading the data. 


pusErrCode Points to the variable that receives an error value. 

pvBuf Points to the buffer that contains the data to write. 

cbBuf Specifies the number of bytes to write. 

pcbBytesWritten Points to the variable receiving the number of bytes written. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_ACCESS_DENIED 
ERROR_BROKEN_PIPE 
ERROR_INVALID_HANDLE 
ERROR_LOCK_VIOLATION 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_DOS_DISK 
ERROR_WRITE. FAULT 
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Comments 


Example 


See Also 


The DosWriteAsync function starts writing at the current file-pointer position. 


' The file-pointer position can be changed by using the DosChgFilePtr function. 


If the specified file has been opened using the write-through flag, the Dos- 
WriteAsyne function writes data to the disk as well as to the file before return- 
ing. If the write-through flag has not been set, the system collects the data in an 
internal file buffer and writes the data to the disk only when the buffer is full. 


The DosWriteAsyne function may write fewer bytes to the file than the number 
specified in the cbBuf parameter if there is not enough space on the disk for all 
of the requested bytes. The cbBuf parameter can be zero without causing an 
error—that is, writing no bytes is acceptable. 


When the DosWriteAsync function has written the data, it clears the RAM 
semaphore pointed to by the hsemRam parameter. If the process uses the sema- 
phore to determine when data is available, it must use the DosSemSet function 
to set the semaphore before calling DosWriteAsync. 


The efficiency with which the Dos WriteAsync function writes to a disk is 
improved when the cbBuf parameter is set to a multiple of the disk’s bytes-per- 
sector size. When cbBuf is set this way, the function writes directly to the disk, 
without first copying the data to an internal file buffer. (The DosQFSInfo func- 
tion retrieves the byters-per-sector value for a disk.) 


This example creates the file abc.ext, sets a RAM semaphore, and calls the 
DosWriteAsyne function to write the contents of the buffer abBuf to a file. 
When any additional processing is finished, the example calls the DosSemWait 
function to wait until DosWriteAsync has finished writing to the file. 


ULONG hsemWrite = 0; 

BYTE abBuf [1024]; 

HFILE hf; ; 

USHORT usAction, cbBytesWritten; 

USHORT usWriteAsyncError; 

DosOpen("abc.ext", &hf, G&usAction, OL, FILE_NORMAL, 
FILE_CREATE, 
OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, OL); 


DosSemSet (&hsemWrite) ; /* sets the semaphore */ 
DosWriteAsync (hf, /* file handle */ 
&hsemwr ite, /* semaphore address */ 
&usWriteAsyncError, /* return-code address */ 
abBuf, /* buffer address */ 
sizeof (abBuf) , /* buffer size */ 
&cbBytesWritten) ; /* address of bytes written */ 


. /* Other processing would go here */ 


DosSemWait (&hsemWrite, -1L); /* waits for DosWriteAsync */ 
if (usWriteAsyncError) { 


. /* Error processing would go here. */ 


DosChgFilePtr, DosOpen, DosQFSInfo, DosReadAsync, DosSemSet, Dos- 
SemWait, DosWrite 


™ DosWriteQueue 
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USHORT DosWriteQueue (hqueue, usRequest, cbBuf, pbBuf, usPriority) 


HQUEUE hqueue; 
USHORT usRequest; 
USHORT cbButf; 
PBYTE pbButf; 
UCHAR usPriority; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/x handle of target queue »/ 
/« request/identification data «/ 
/x number of bytes to write x/ 
/x pointer to buffer containing element to write «/ 
/« priority of element to write x/ 


The DosWriteQueue function writes an element to the specified queue. The 
position of the element in the queue is determined by the value that was 
specified in the fQueueOrder parameter of the DosCreateQueue function when 
the queue was created; if the value of this parameter was set to 0x0002 (priority 
queue), the usPriority parameter of the DosWriteQueue function can be used to 
set the priority of the element. After the element is written, the process that 
owns the queue may read the element by using the DosPeekQueue or DosRead- 
Queue function. 


hqueue Identifies the queue to be written to. This handle must have been pre- 
viously created or opened by using the DosCreateQueue or DosOpenQueue 
function. 


usRequest Specifies a program-supplied event code. MS OS/2 does not use 
this field; it is reserved for the program’s use. The queue owner can retrieve this 
value by using the DosPeekQueue or DosReadQueue function. 


cbBuf Specifies the number of bytes to be copied to the buffer that is pointed 
to by the pbBuf parameter. 


pbBuf Points to the buffer that contains the element to be written to the 
queue. 


usPriority Specifies the element priority. This parameter can be any value 
from 0 through 15; 15 is the highest priority. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_QUE_INVALID_HANDLE 
ERROR_QUE_NO_MEMORY 


The DosWriteQueue function returns an error value if the queue has been 
closed by the process that owns it. 


If the queue owner uses a RAM semaphore to notify it when elements are added 
to the queue, the semaphore must be shared. If the notifying semaphore is a sys- 
tem semaphore, the writing process must have opened the semaphore by using 
the DosOpenSem function. 


This example creates a-queue and calls the DosWriteQueue function to write the 
string “Hello World” to the queue: 


HQUEUE hqueue; 

DosCreateQueue (&hqueue, O, "\\queues\\abc. que") ; 

DosWr iteQueve (hqueue, * handle to queue */ 
ce) 


3 /* request data */ 
11, . f* length of data */ 
"Hello World", /* data buffer * 
0); /* element priority */ 


DosCreateQueue, DosOpenQueue, DosReadQueue 
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B KbdCharin 


USHORT KbdCharin(pkbci, fWait, hkbd) 
PKBDKEYIN FO pkbei: / pointer to structure for keystroke info. »/ 


USHORT fWait; 
HKBD hkba; 


Parameters 


Return Value 


Comments 


/» wait/no-wait flag ; x/ 
/« keyboard handle _ »/ 


The KbdCharIn function. retrieves ‘character and scan-code information from a 
logical keyboard. The function copies the information to the structure pointed to 
by the pkbci parameter. Keystroke information includes the character value of a 
given key, the scan code, the keystroke status, the state of the shift keys, and 
the system time (in milliseconds) when the keystroke occurred. For information 
on scan codes, key codes, and MS OS/2 control and editing keys, see Chapter 
5, “File Formats.” 


The KbdCharIn function is a family API function. 


pkbci_ Points to the KBDKEYINFO structure that receives the keystroke infor- 
mation. The KBDKEYINFO structure has the following form: 
typedef struct _KBDKEYINFO { 
UCHAR chChar 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNilsShift; 
USHORT fsState; 
ULONG time; 
} KBDKEYINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


[Wait Specifies whether to wait for keystroke information if none is available. 
If this parameter is IO_WAIT, the function waits for a keystroke if one is not 
available. If the parameter is 10_ NOWAIT, the function returns. immediately 
whether or not it retrieved any keystroke information. The fbStatus field in the 
KBDKEYINFO structure specifies whether a keystroke is received. The fbStatus 
field is nonzero if a keystroke is received or zero if not. 


hkbd Identifies the logical keyboard. The handle must have been creuted 3 pre- 
viously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_F OCUS_REQUIRED 
ERROR_KBD_INVALID_IOWAIT 


The KbdCharIn function copies and removes keystroke information from the 
input buffer of the specified logical keyboard. Although echo mode for the logi- 
cal keyboard may be turnéd on, KbdCharIn does not echo the characters it 
reads. If the keyboard is in ASCII mode, KbdCharIn retrieves keystroke infor- 
mation for each key pressed except shift keys and MS OS/2 cTRL keys. If the 
keyboard is in binary mode, KbdCharIn retrieves keystroke information for any 
key pressed except shift keys. In. most cases, a shift key is pressed in combina- 
tion with other keys to create a single keystroke. In binary mode with shift 
report turned on, a key by itself creates a keystroke that this function can 
retrieve. For more information on binary mode and shift-report mode, see the 
KbdSetStatus function. 
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The KbdCharlIn function retrieves extended ASCII codes, such as when the ALT 
key and another key, called the primary key, are pressed simultaneously. When 
the function retrieves an extended code, it sets the chChar field of the 
KBDKEYINFO structure to 0x0000 or Ox00EO and copies the extended code to 
the chScan field. The extended code is usually the scan code of the primary key. 
In ASCII mode, the function retrieves only complete extended codes, which 
means that if both bytes of the extended code do not fit in the buffer, neither 
byte is retrieved. For more information on extended ASCII codes, see Appen- 
dix C, “Country and Code-Page Information.” 


This function must be called twice to retrieve a code for a double-byte character 
set (DBCS). If the code retrieved is the first byte of a double-byte character, the 
fbStatus field of the KBDKEYINFO structure is set to 0x0080. 


Restrictions In real mode, the following restrictions apply to the KbdCharIn function: 
@ It does not copy the system time to the KBDKEYINFO structure and 
there is no interim character support. 
HB It retrieves characters only from the default logical keyboard (handle 0). 
H The fbStatus field may be 0x0000 or SHIFT_KEY_IN. 
@ The hkbd parameter is ignored. 
Example This example calls the KbdCharIn function to retrieve a charstet; and then dis- 
plays the character on the screen: 
KBDKEYINEO kbci; 


KbdCharIn(&kbci, /* structure for data a, 
IO_WAIT, /* waits for key 
O); /* keyboard handle “4 
VioWrtTTY (&kbci.chChar, 1, 0); 
See Also KbdGetStatus, KbdOpen, KbdPeek, KbdSetStatus, KbdStringIn 


KbdClose 


USHORT KbdClose { hkbd) 
HKBD hkbd; /x keyboard handle »/ 


The KbdClose function closes the specified logical keyboard. The function 
removes any remaining keystrokes from the input buffer and automatically frees 
the focus (if the logical keyboard has it). 


The default keyboard cannot be closed. If you specify the default keyboard (han- 
dle 0), the KbdClose function ignores the request. 


Parameters hkbd Identifies the logical keyboard to close. The handle must have been 
created previously by using the KbdOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_KBD_LINVALID_HANDLE 
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Example 


See Also 


KbdDeRegister 


This example opens a logical keyboard and calls KbdClose to close it: 
HKBD hkbd; 


a ae a. .y 
KbdOpen (&hkbd) ; 


KbdClose (hkbd) ; 


KbdFlushBuffer, KbdFreeFocus, KbdOpen 


USHORT KbdDeRegister( void) 


Parameters 


Return Value 


See Also 


KbdFlushBuffer 


The KbdDeRegister function restores the default Kbd subsystem and releases 
any previously registered Kbd subsystem. The function restores the default Kbd 
subsystem for all processes in the current screen group. 


Once a process registers a Kbd subsystem, no other process in the screen group 
may register a Kbd subsystem until the default subsystem is restored. Only the 
process registering a Kbd subsystem may call the KbdDeRegister function to 
restore the default subsystem. 


This function has no parameters. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_KBD_DEREGISTER 
KbdRegister 


USHORT KbdFlushBuffer(hkbd) 
HKBD hkba; /« keyboard handle »/ 


Parameters 


Return Value 


Restrictions 


The KbdFlushBuffer function removes all keystroke information from the input 
buffer of the specified logical keyboard, but only if the keyboard has the focus or 
is the default keyboard. 


The KbdFlushBuffer function is a family API function. 


hkbd_ Identifies the logical keyboard to clear. The handle must have been 
created previously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


In real mode, the following restriction applies to the KbdFlushBuffer function: 


@ The hkbd parameter is ignored. 


Example 


See Also 


KbdFreeFocus 
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This example opens a logical keyboard and calls KbdFlushBuffer to remove any 
keystrokes from the input buffer: 


HKBD hkbd; 
KbdOpen (&hkbd) ; 


KbdF lushBu f fer (hkbd) ; 


KbdCharIn 


USHORT KbdFreeFocus(hkba) 


HKBD hkbd; 


Parameters 
Return Value 


Comments 


Example 


See Also 


KbdGetCp 


/« keyboard handle «/ 


The KbdFreeFocus function frees the focus from the specified logical keyboard. 
Other logical keyboards can then use the focus. 


hkbd_ Identifies the logical keyboard that loses the focus. The handle must 
have been created previously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. . 


If a process has been waiting for the focus as a result of calling the KbdGet- 
Focus function, MS OS/2 assigns the focus to the logical keyboard as soon as it 
is free. If more than one process is waiting, MS OS/2 chooses a logical keyboard 
and assigns the focus. The other processes continue to wait until the focus is 
free. 


This example frees a logical keyboard: if other logical keyboards have been wait- 
ing, MS OS/2 assigns the focus to one of them; if no other logical keyboards 
have been waiting, MS OS/2 uses the default keyboard: 


HKBD hkbd; 

KbdOpen (&hkbda) ; 

KbdGetFocus (IO_WAIT, hkbd); /* gets focus */ 
KbdFreeFocus (hkbd) ; /* frees focus */ 


KbdGetFocus, KbdOpen 


USHORT KbdGetCp(u/Reserved, pidCodePage, hkbd) 


ULONG u/Reserved; 


/x must be zero »/ 


PUSHORT pidCodePage; /«x pointer to code-page identifier »/ 


HKBD hkbd; 


/x keyboard handle »/ 


The KbdGetCp function retrieves the current code-page identifier for the speci- 
fied logical keyboard. The code-page identifier defines which translation table 
MS OS/2 uses to translate keystrokes into character values. The KbdGetCp 
function copies the identifier to the variable pointed to by the pidCodePage 
parameter. 
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Parameters ulReserved Specifies a reserved value; must be zero. 


pidCodePage Points to the variable that receives the code-page identifier. The 
following are the valid code-page numbers: 


Number Code page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


hkbd Identifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments The code-page identifier may be any value specified in a codepage command in 


the config.sys file. The identifier is 0x0000 if MS OS/2 is using the default trans- 
lation table for the logical keyboard. 


For a description of the possible code-page identifiers and translation tables, see 
Appendix C, “Country and Code-Page Information.” 

Example This example calls the KbdGetCp function to identify which code page is being 
used to translate scan codes for the specified logical keyboard. 
USHORT idCodePage; 


KbdGetCp (OL, /* must be zero */ 
&idCodePage, /* pointer to code-page identifier */ 
0); /* keyboard handle */ 
See Also DosGetCp, KbdOpen, KbdSetCp 
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USHORT KbdGetFocus(fWait, hkbd) 
USHORT fwait; /« wait/no-wait flag »/ 
HKBD hkbd; /« keyboard handle »/ 


The KbdGetFocus function retrieves the focus for the specified logical keyboard. 
The focus determines which logical keyboard receives keystrokes from the physi- 
cal keyboard. A logical keyboard cannot receive keystrokes unless it has the 
focus. 


A process can retrieve the focus at any time, but it must wait if the focus is 
already being used by another process or thread. If a process has the focus, 
another process cannot receive the focus until the original process frees it by 
using the KbdFreeFocus function. If more than one process is waiting for the 
focus, MS OS/2 chooses which one receives the focus. 


An application must set the focus to an opened keyboard handle before calling 
functions such as KbdCharIn. 


Parameters 


Return Value 


Example 


See Also — 


KbdGetStatus 
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fWait Specifies whether to wait for the focus to become available. If this 
parameter is IO_WAIT, the function waits for the focus. If the parameter is 
IO_NOWAIT, the function returns immediately whether or not it retrieved the 
focus. 


hkbd_ Identifies the logical keyboard that receives the focus. The handle must 
have been created previously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_FOCUS_ALREADY_ACTIVE 
ERROR_KBD_UNABLE_TO_FOCUS 


This example opens a logical keyboard and calls KbdGetFocus to retrieve the 
focus for the opened keyboard. Once the KbdFreeFocus function is called, the 
focus goes to any process that is waiting for it by calling KbdGetFocus. If no 
process is waiting, MS OS/2 uses the default keyboard: 

HKBD hkbd; 


KbdOpen (&hkbd) ; 
KbdGetBocus (0_ WAIT, hkbd); /* retrieves focus of logical keyboard */ 


KbdFreeFocus (hkbd) ; /* frees the focus */ 


KbdCharlIn, KbdFreeFocus, KbdOpen 


USHORT KbdGetStatus (pkbstKbdinfo, hkbd) 
PKBDINFO pkbstKbdinfo; /« pointer to structure for keyboard status «/ 


HKBD hkbd; 


Parameters 


Return Value 


| keyboard handle »/ 


The KbdGetStatus function retrieves the status of the specified logical keyboard. 
The keyboard status specifies the state of the keyboard echo mode, input mode, 
turnaround character, interim character flags, and shift state. 


The KbdGetStatus function is a family API function. 


pkbstKbdInfo Points to the KBDINFO structure that receives the keyboard 
status. The KBDINFO structure has the following form: 


typedef struct _KBDINFO { 
SHORT cb; : 
USHORT fsMask; 
USHORT chTurnAround; 
USHORT fsInterim; 
USHORT fsState; 
} KBDINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hkbd _ {dentifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_KBD_INVALID_LENGTH 
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Comments _ Although the initial status of a logical keyboard depends on the system, the logi- 
cal keyboard typically has echo and ASCII modes turned on, and has a single- 
byte turnaround character whose value corresponds to the ENTER key. 


Restrictions In real mode, the following restriction applies to the KbdGetStatus function: 


@ Interim and turnaround characters are not supported. 


Example This example calls the KbdGetStatus function to retrieve the status of the 
default keyboard. It then checks to see if echo mode is turned on: 


KBDINFO kbstInfo; 
kbstInfo.cb = sizeof (kbstInfo) ; /* length of status buffer */ 
KbdGetStatus (&kbstInfo, 0); 
if (kbstInfo.fsMask & KEYBOARD_ECHO_ON) { 
VioWrtTTY("Echo is on\n\r", 12, 0); 


See Also KbdSetStatus, KbdOpen 


KbdOpen 


USHORT KbdOpen(phkba) 
PHKBD phkba; /« pointer to variable for keyboard handle «/ 


The KbdOpen function opens a logical keyboard and creates a unique handle 
that identifies a logical keyboard for use in subsequent Kbd (or other MS OS/2) 
functions. The KbdOpen function initializes the logical keyboard to use the 
default system code page. 


Parameters phkbd Points to the variable that receives the handle of the logical keyboard. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

Comments Any MS OS/2 function that can receive input through a handle (for example, the 


DosRead function) can use the handle created by the KbdOpen function. 


Example This example calls the KbdOpen function to create and open a handle for a logi- 
cal keyboard. Before you can access this logical keyboard, you must call the 
KbdGetFocus function to retrieve the focus: 
HKBD hkbd; 


KbdOpen (&hkbd) ; 
KbdGetFocus (IO_WAIT, hkbd); 


See Also DosRead, KbdClose, KbdGetFocus 


KbdPeek 


USHORT KbdPeek( pkbciKeyinfo, hkbd) 
PKBDKEYINFO pkbcikKeyinfo; /x pointer to structure for keystroke info. «/ 
HKBD hkba; /» keyboard handle »/ 


The KbdPeek function retrieves character and scan-code information from a log- 
ical keyboard. The function copies information to the structure pointed to by the 
pkbciKeyInfo parameter. The keystroke information includes the character value 


Parameters 


Return Value 


Comments 


Restrictions 
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of the key, the scan code, the keystroke status, the state of the shift keys, and 
the system time (in milliseconds) when the keystroke occurred. For information 
on scan codes, key codes, and MS OS/2 control and editing keys, see Chapter 
5, “File Formats.” 


The KbdPeek function is a family API function. 


pkbciKeyInfo Points to the KBDKEYINFO structure that receives the key- 
stroke information. The KBDKEYINFO structure has the following form: 


typedef struct _KBDKEYINFO { 
UCHAR chChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR PNlsShift; 
USHORT fsState; 
ULONG time; 
} KBDKEYINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hkbd_ Identifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The KbdPeek function copies but does not remove keystroke information from 
the input buffer of the specified logical keyboard. Although echo mode for the 
logical keyboard may be turned on, the KbdPeek function does not echo the 
characters it reads. If the keyboard is in ASCII mode, KbdPeek retrieves key- 
stroke information for each key pressed, except shift keys and MS OS/2 CTRL 
keys. If the keyboard is in binary mode, KbdPeek retrieves keystroke informa- 
tion for any key pressed, except shift keys. In most cases, a shift key is pressed 
in combination with other keys to create a single keystroke. In binary mode with 
shift report turned on, a shift key by itself creates a keystroke that this function 
can retrieve. For more information on ay mode and shift-report mode, see 
the KbdSetStatus function. 


The KbdPeek function retrieves extended ASCII codes, such as when the ALT 
key and another key, called the primary key, are pressed simultaneously. When 
the KbdPeek function retrieves an extended ASCII code, it sets the chChar field 
of the KBDKEYINFO structure to 0x0000 or 0x00E0 and copies the code to the 
chScan field. The extended code is usually the scan code of the primary key. In 
ASCII mode, the function retrieves only complete extended codes, which means 
that if both bytes of the extended code do not fit in the buffer, neither byte is 
retrieved. For more information on extended ASCII codes, see Appendix C, 
“Country and Code-Page Information.” 


The KbdPeek function must be called twice to retrieve a code for a double-byte 
character set (DBCS). If the code retrieved is the first byte of a double-byte 
character, the fbStatus field of the KBDKEYINFO structure is set to 0x0080. 


In real mode, the following restrictions apply to the KbdPeek function: 

™ It does not copy the system time to the KBDKEYINFO structure, and 
there is no interim character support. 

™ It retrieves characters only from the default logical keyboard (handle 0). 

™ The fbStatus field may be 0x0000 or SHIFT_KEY_IN. 

™ The hkbd parameter is ignored. 
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Example This example calls the KbdPeek function to read a character from the default 
keyboard without removing it from the keyboard input buffer. If there is already 
a character in the buffer, the fSiatus field specifies this by setting the sixth bit 
(0x40): 


KBDKEYINFO kbcikeylInfo; 


KbdPeek (&kbcikeyInfo, O); 
if (kbcikKeyInfo.fbStatus & 0x40) { 


See Also KbdCharIn, KbdGetStatus, KbdOpen, KbdSetStatus 


KbdRegister 

USHORT KbdRegister(pszModuleName, pszEntryName, fFunctions) 
PSZ pszModuleName; _/s pointer to string for modulename ——+/ 
PSZ pszEntryName; /» pointer to string for entry-point name «/ 
ULONG fFunctions; /« function flags x/ 


The KbdRegister function registers a Kbd subsystem for the specified logical’ 
keyboard. The function temporarily replaces the one or more default Kbd func- 
tions, as specified by the fFunctions parameter, with the function(s) in the mod- 
ule named by the pszModuleName parameter. Once KbdRegister replaces a 
function, MS OS/2 passes any subsequent call to the replaced function to a func- 
tion in the given module. If you do not replace a function, MS OS/2 continues 
to call the default Kbd function. 


Parameters pszModuleName Points to the null-terminated string that contains the name 
- of the dynamic-link module specifying the replacement Kbd functions. The string 
must be a valid filename. 


pszEntryName Points to the null-terminated string that contains the dynamic- 
link entry-point name of the function that replaces the specified Kbd function(s). 
For a full description, see the following “Comments” section. 


fFunctions Specifies the flags for the function(s) to replace. This parameter 
can be any combination of the following values: 


Value Meaning 
KR_KBDCHARIN Replace KbdCharIn. 
KR_KBDPEEK Replace KbdPeek. 
KR_KBDFLUSHBUFFER Replace KbdFlushBuffer. 
KR_KBDGETSTATUS Replace KbdGetStatus. 
KR_KBDSETSTATUS Replace KbdSetStatus. 
KR_KBDSTRINGIN Replace KbdStringIn. 
KR_KBDOPEN Replace KbdOpen. 
KR_KBDCLOSE Replace KbdClose. 
KR_KBDGETFOCUS Replace KbdGetFocus. 
KR_KBDFREEFOCUS Replace KbdFreeFocus. 


KR_KBDGETCP Replace KbdGetCp. 


Return Value 


Comments 


Value 


KR_KBDSETCP 
KR_KBDXLATE 
KR_KBDSETCUSTXT 


KbdRegister 


Meaning 
Replace KbdSetCp. 


Replace KbdXlate. 
Replace KbdSetCustxt. 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_INVALID_ASCIIZ 
ERROR_KBD_INVALID_MASK 
ERROR_KBD_REGISTER 


MS OS/2 passes a Kbd function to the given module by preparing the stack and 
calling the function pointed to by the pszEntryName parameter. The specified 
module must export the entry-point function name. The entry-point function 
must check the function code on the stack to determine which function is being 
requested, and then pass control to the appropriate function in the module. The 
entry-point function may then access any additional parameters placed on the 
stack by the original call to KbdRegister. 


Only one process in a screen group may use the KbdRegister function at any 


given time. That is, only one process can replace Kbd functions at any given 
time. The process can restore the default Kbd functions by calling the KbdDe- 
Register function. A process can replace Kbd functions any number of times, 
but it may do so only by first restoring the default functions, and then reregis- 


tering the new functions. 


The entry-point function (FuncName) must have the following form: 


SHORT FAR FuncName(selDataSeg, usReserved1, fFunction, 
ulReserved2, usParamI1, usParam2, usParam3, usParam4, 


usParam5, usParam6) 
SEL selDataSeg; 
USHORT usReserved1; 
USHORT fFunction; 
ULONG ulReserved2; 
USHORT usParam1; 
USHORT usParam2; 
USHORT usParam3; 
USHORT usParam4; 
USHORT usParam5; 
USHORT usParam6; 


Parameters 


selDataSeg 


usReserved] 


Description 


Specifies the data-segment selector of the process that 
calls the Kbd function. 


Specifies a reserved value that must not be changed. 
This value represents a return address for the MS 
OS/2 function that routes Kbd function calls. 
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See Also 


Parameters Description 
fFunction Specifies the function code of the function request. 
This parameter can be one of the following values: 
Value Meaning 
0x0000 KbdCharIn called. 
0x0001 KbdPeek called. 
0x0002 KbdFlushBuffer called. 
0x0003 KbdGetStatus called. 
0x0004 KbdSetStatus called. 
0x0005 KbdStringIn called. 
0x0006 KbdOpen called. 
0x0007 KbdClose called. 
0x0008 KbdGetFocus called. 
0x0009 KbdFreeFocus called. 
0x000A. KbdGetCp called. 
0x000B _ _KbdSetCp called. 
0x000C KbdXlate called. 
0x000D KbdSetCustXt called. 
ulReserved2 Specifies a reserved value that must not be changed. 


This parameter represents the return address of the 
program that calls the specified Kbd function. 


usParamI1-usParam6 Specify up to six unsigned values passed with the call 
to the Kbd function. The number and type of parame- 
ters used depend on the specific function. 


The entry-point function should determine which function is requested and then 
carry out an appropriate action by using the passed parameters. If necessary, the 
entry-point function can call a function within the same module to carry out the 
task. The entry-point or replacement function must leave the stack in the same 
state as it was received. This is required since the return addresses on the stack 
must be available in the correct order to return control to the program that origi- 
nally called the KbdRegister function. 


The registered function should return ~ 1 if it wants the original function called, 
0 if no error occurred, or an error value. 


In general, if the replacement function needs to access the keyboard, it must use 


the input-and-output control functions for the keyboard. For more information, 


see Chapter 3, “Input-and-Output Control Functions.” 
The KbdRegister function itself cannot be replaced. 


KbdDeRegister, KbdFlushBuffer 
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™@ KbdSetCp 


USHORT KbdSetCp(usReserved, idCodePage, hkbd) 
USHORT usReserved; /« must be zero »/ 
USHORT idCodePage; /« code-page identifier «/ 
HKBD hkba; /x keyboard handle _ «/ 


The KbdSetCp function sets the code-page identifier for the specified logical 
keyboard. The code-page identifier defines which translation table MS OS/2 uses 
to translate keystrokes into character values. The code-page identifier may be 
any value specified in a codepage command in the config.sys file, or 0x0000 for 
the default translation table for the logical keyboard. 


The KbdSetCp function also clears the input buffer of the logical keyboard. 


Parameters usReserved Specifies a reserved value; must be zero. 


idCodePage Specifies the code-page identifier. If the identifier is 0x0000, the 
default translation table is used. The following are the valid code-page numbers: 


Number Code page 


437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 

865 Nordic 


hkbd Identifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 


Comments For a description of the possible code-page identifiers and translation tables, see 
Appendix C, “Country and Code-Page Information.” 


Example This example calls KbdSetCp to change the Kbd subsystem so that it uses the 
U.S. multilingual code page (850) when translating keystrokes for the default 
keyboard. The code page must be installed by the config.sys file or this function 
returns an error value: 


KbdSetCp (0, /* reserved */ 
850, /* code-page identifier wp 
O); /* keyboard handle */ 


See Also DosSetCp, KbdGetCp, KbdOpen, KbdSetCustXt 
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™ KbdSetCustXt 


USHORT KbdSetCustxt(pusTransTbi, hkbd) 
PUSHORT pusTransTbi; /« pointer to translation table «/ 
HKBD hkbe; /« keyboard handle »/ 


The KbdSetCustXt function installs a custom translation table for the specified 
logical keyboard. MS OS/2 uses the translation table to generate character 
values for all subsequent keystrokes from the logical keyboard. 


The KbdSetCustXt function does not copy the translation table, so the process 
must maintain the table in memory while it is in use, where it remains until the 
process calls the KbdSetCp or KbdSetCustXt function to set another translation 
table, or calls the KbdClose function to close the logical keyboard. 


Parameters pusTransTbl Points to the translation table. The table has the size and format 
described in Appendix C, “Country and Code-Page Information.” 


hkbd Identifies the logical keyboard that uses the new code page. The handle 
must have been created previously by using the KbdOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
See Also DosSetCp, KbdClose, KbdOpen, KbdSetCp, KbdXlate 


M@ KbdSetFgnd 
USHORT KbdSetFgnd( void) 


The KbdSetFgnd function raises the priority of the foreground keyboard’s 
thread. This function is used by a Kbd subsystem, not by an application. 


Parameters This function has no parameters. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 


@ KbdSetStatus 


USHORT KbdSetStatus( pkbstKbdinfo, hkbd) 
PKBDINFO pkbstKbdinfo; /« pointer to structure for keyboard status «/ 
HKBD hkbd; /x keyboard handle »/ 


The KbdSetStatus function sets the status for the specified logical keyboard. The 
keyboard status specifies the state of the keyboard echo mode, input mode, turn- 
around character, interim character flags, and shift state. 


The KbdSetStatus function is a family API function. 


Parameters 


Return Value 


Comments 


Restrictions 


Example 


See Also 


KbdStringIn 
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pkbstKbdInfo Points to the KBDINFO structure that contains the keyboard 
status. The KBDINFO structure has the following form: 
typedef struct _KBDINFO { 
USHORT cb; 
USHORT fsMask; 
USHORT chTurnAround; 
USHORT fsInterim; 
USHORT fsState; 
} KBDINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hkbd Identifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_KBD_INVALID_ECHO_MASK 
ERROR_KBD_INVALID_INPUT_MASK 
ERROR_KBD_INVALID_LENGTH 


In most cases, a shift key is pressed in combination with other keys to create a 
single keystroke. In binary mode with shift report turned on, a shift key by itself 
creates a keystroke that the KbdCharIn or KbdPeek function can retrieve. 


In real mode, the following restrictions apply to the KbdSetStatus function: 


™ Interim and turnaround characters are not. supported. 
™ Binary mode with echo mode on is not supported. 
@ The hkbd parameter is ignored. 


This example retrieves the current status of the default keyboard, masks the 
ASCII-mode bit, uses the OR operator to set the binary-mode bit, and calls the 
KbdSetStatus function to change the keyboard status to binary mode: 

KBDINEO kbstInfo; 


kbstInfo.cbh = sizeof (kbstInfo) ; 
KbdGetStatus (&kbstInfo, 0); /* gets current status */ 


kbstiInfo.fsMask = 
(kbstInfo.fsMask & OxOOF7) /* masks out ASCII mode */ 
| Ox0004; /* OR into binary mode */ 

KbdSetStatus (&kbstInfo, 0); /* sets new status a/ 


KbdCharIn, KbdGetStatus, KbdOpen, KbdPeek 


USHORT KbdStringIin( pchBuffer, psibLength, fWait, hkbd) 


PCH pchBuffer; 


USHORT fWait; 


/« pointer to buffer for string s/ 
PSTRINGINBUF psibLength; /« pointer to structure for string length «/ 
/» wait/no-wait flag »/ 
/» keyboard handle s/ 


HKBD hkbd; 


The KbdStringIn function reads a string of characters from a logical keyboard. 
The function copies the character value of each keystroke to the buffer pointed 
to by the pchBuffer parameter. Depending on the input mode of the keyboard 
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Parameters 


Return Value 


Comments 


Restrictions 


and on the value of the fWait parameter, KbdStringIn continues to copy charac- 
ters until it fills the buffer, retrieves the turnaround character, or reaches the 
end of the buffer. 


The KbdStringIn function is a family API function. 


pchBuffer Points to the buffer that receives the character string. 


psibLength Points to the STRINGINBUF structure that contains the length of 
the buffer that receives the string. The STRINGINBUF structure has the follow- 
ing form: 
typedef struct _STRINGINBUF { 

USHORT cb; 


USHORT cchin; 
} STRINGINBUE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


fWait Specifies whether to wait for the entire string to be read. If this param- 
eter is IO_WAIT, the function waits for all characters up to the next turn- 
around character or until it reaches the end of the buffer. If the parameter is 
IO_.NOWAIT, the function returns immediately with whatever characters are 
available. 


hkbd Identifies the logical keyboard to read from. The handle must have been 
created previously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The KbdStringIn function removes keystroke information from the input buffer 
of the specified logical keyboard as it copies a character. If echo and ASCII 
modes are turned on, the function echoes characters on the screen as they are 
typed. If the keyboard is in ASCII mode, the function retrieves a character for 
each key pressed, except shift keys and MS OS/2 CTRL and editing keys. If the 
keyboard is in binary mode, the function retrieves a character for any key 
pressed except shift keys. 


The KbdStringIn function can retrieve extended ASCII codes, such as when the 
ALT key, and another key, called the primary key, are pressed simultaneously. 
When the function retrieves an extended code, the first character is 0x0000 or 
Ox00E0 and the second is the extended code. The extended code is usually the 
scan code of the primary key. In ASCII mode, the function retrieves only com- 
plete extended codes, which means that if both bytes of the extended code do 
not fit in the buffer, neither byte is retrieved. For more information on extended 
ASCII codes, see Appendix C, “Country and Code-Page Information.” 


In ASCII mode, KbdStringIn recognizes the MS OS/2 editing keys. These keys 
can be used to display and edit the previously entered string. The KbdStringIn 
function permits editing of the previous string only if the cchIn field of the 
STRINGINBUF structure is set to the length of the previous string before the 
function is called. If this field is set to zero, the line cannot be edited. 


In real mode, the following restriction applies to the KbdStringIn function: 


@ The hkbd parameter is ignored. 
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Example . This example calls the KbdStringIn function to read a character string from the 
default keyboard. In ASCII mode, the function waits for the RETURN key to be 
pressed; in binary mode, it waits for the buffer to be filled: 

CHAR achBuf [40]; 


STRINGINBUE kbsiBuf; 
kbsiBuf.cbh = sizeof (achBuf) ; 


KbdStringIn(achBuf, /* address of buffer */ 
&kbsiBuf, /* address of length structure */ 
IO_WAIT, /* waits for characters * 
O); /* keyboard handle / 
VioWrtTTY("\n", 1, O); * sends linefeed character */ 
VioWrtTTY(achBuf, kbsiBuf.cchIn, 0); /* displays string & 
See Also DosRead, KbdCharIn, KbdGetStatus, KbdOpen, KbdSetStatus 
KbdSynch 


USHORT KbdSynch( fWait) 
USHORT fWait; /« wait/no-wait flag »/ 


The KbdSynch function synchronizes access to the keyboard device driver. 


This function should be used by a Kbd subsystem, not by an application. You 
cannot replace the KbdSynch function by using the KbdRegister function. 


Parameters fWait Specifies whether to wait for access to the keyboard router if access is 
not available. If this parameter is IOLWAIT, the function waits for access to the 
keyboard router. If the parameter is IOLNOWAIT, the function does not wait 
and returns immediately. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
Comments The KbdSynch function requests an exclusive system semaphore that blocks all 


other threads within a screen group until the semaphore is cleared. This sema- 
phore is cleared when a called Kbd function returns. 


See Also DosDevIOCtl, KbdRegister 


KbdXlate 


USHORT KbdxXlate ( pkbx/KeyStroke, hkbd) 
PKBDXLATE pkbxiKeyStroke; /« pointer to structure for scan code »/ 
HKBD hkbd; /« keyboard handie »/ 


The KbdXlate function translates a scan code and its shift states into a character 
value. The function uses the current translation table of the specified logical key- 
board. 


In order to be translated, accent-key combinations, double-byte characters, and 
extended ASCII characters may require several calls to the KbdXlate function. 
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Parameters 


Return Value 


See Also 


pkbxlKeyStroke Points to the KBDTRANS structure that contains the scan 


code to translate. It also receives the character value when the function returns. 


we than £-.11....-3 0 
The KB BDTRANS structure has the following form: 


typedef struct _KBDTRANS { 
UCHAR chChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNisShift; 
USHORT fsState; 
ULONG time; 
USHORT fsDD; 
USHORT fsXlate; 
USHORT fsShift; 
USHORT sZero; 

} KBDTRANS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hkbd Identifies the logical keyboard. The handle must have been created pre- 
viously by using the KbdOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


DosMonReg, KbdOpen, KbdSetCustXt 


—M MouClose 
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USHORT MouClose(hmou) 


HMOU hmou; 


Parameters 


Return Value. 


Example 


See Also 


MouDeRegister 


/«x mouse handle / 


The MouClose function closes the mouse identified by the given handle. The 
function removes the mouse pointer from the screen only if the process is the 
last one in the screen group to have the mouse open. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle then calls the MouClose function to close 
the open handle: 


HMOU hmou; 
MouOpen(OL, &hmou) ; 


MouC lose (hmov) ; 


MouOpen 


USHORT MouDeRegister( void) 


Parameters 


Return Value 


See Also 


The MouDeRegister function restores the default Mou subsystem functions and 
releases any previously registered Mou subsystem. This function restores the 
default Mou subsystem for all processes in the current screen group. 


Once a process registers a Mou subsystem, no other process in the screen group 
may register a Mou subsystem until the default subsystem is restored. Only the 
process that registers a Mou subsystem may call the MouDeRegister function to 
restore the default subsystem. 


This function has no parameters. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_DEREGISTER 
MouRegister 
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@ MouDrawPtr 


USHORT MouDrawPtr(hmou) 


HMOU hmou; 


Parameters 


Return Value 


Comments 


Example 


See Also 


M@ MouFlushQue 


/«x mouse handle «/ 


The MouDrawPtr function enables the mouse pointer to be drawn on the 
screen, using the pointer shape defined by the most recent call to the 
MouSetPtrShape function. The MouDrawPtr function releases any exclusion 
rectangle that may have been previously set by using the MouRemovePtr func- 
tion. An exclusion rectangle defines a rectangular region of the screen in which 
MS OS/2 will not display the pointer. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be the following: 
ERROR_MOUSE_NO_DEVICE 


The MouDrawPtr function does not itself draw the mouse pointer. Instead, it 
directs MS OS/2 to call the mouse device driver at each mouse interrupt. If the 
mouse device driver has been disabled (by the MouSetDevStatus function), 
MouDrawPtr releases the current exclusion rectangle but does not draw the 
pointer. 


This example creates a mouse handle then calls the MouDrawPtr function to 
enable the mouse pointer to be drawn on the screen: 
HMOU hmou; 


MouOpen(OL, &hmou) ; 
MouDrawPtr (hmou) ; 


MouOpen, MouRemovePtr, MouSetDevStatus, MouSetPtrShape 


USHORT MouFlushQue (hmou) 


HMOU hmou; 


Parameters 


Return Value 


/x mouse handle «/ 


The MouFlushQue function removes any existing mouse events from the mouse 
event queue. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


Example 


See Also 
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This example creates a mouse handle then calls the MouFlushQue function to 
remove any events from the existing mouse event queue: 


HMOU hmou; 
MouOpen(OL, &hmou) ; 


MouF lushQue (hmou) ; 


MouGetNumQueEl, MouOpen, MouReadEventQue 


MouGetDevStatus 


USHORT MouGetDevStatus(pfsDevStatus, hmou) 
PUSHORT pfsDevStatus; /» pointer to buffer for status «/ 


HMOU hmou; 


Parameters 


Return Value 


Example 


See Also 


/« mouse handle »/ 


The MouGetDevStatus function retrieves the device status for the specified 
mouse. 


pfsDevStatus Points to the variable that receives the device status. It can be 
any combination of the following values: 


Value Meaning 

MOUSE_QUEUEBUSY Event queue is busy with input/output 
; (I/O). 

MOUSE_BLOCKREAD Block read is in progress. 

MOUSE_FLUSH Flush buffer is in progress. 


MOUSE_UNSUPPORTED_MODE Mouse device driver is disabled because 
of unsupported mode. 


MOUSE_DISABLED Mouse device driver is disabled. 
MOUSE_MICKEYS Mouse motion is given in mickeys, not in 
pels. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle then calls the MouGetDevStatus function 
to retrieve the status for the mouse identified by the handle: 


USHORT fsDevStatus; 
HMOU hmou; 
MouOpen(OL, &hmou) ; 
MouGetDevStatus (&fsDevStatus, hmou) ; 
if (fsDevStatus & MOUSE_DISABLED | | 
fsDevStatus & MOUSE_UNSUPPORTED_MODE) 
VioWrtTTY ("mouse is disabled\r\n", 19, 0); 


MouOpen, MouSetDevStatus 
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mM MouGetEventMask 
USHORT MouGetEventMask ( pfsEvents, hmou) 


PUSHORT pfsEvents; 
HMOU hmou; 


Parameters 


Return Value 


Comments 
Example 


/« pointer to buffer for event mask «/ 
/» mouse handle a/ 


The MouGetEventMask function retrieves the event mask for the specified 
mouse. The event mask specifies the user actions that cause MS OS/2 to gen- 
erate mouse events. MS OS/2 responds to a user action by copying a mouse 
event to the event queue. 


pfsEvents Points to the variable that receives the event mask. It can be any 
combination of the following values: 


Value _ Meaning 

MOUSE_MOTION Mouse motion. 

MOUSE_MOTION_WITH_BN1_DOWN Mouse motion with button-1-down 
event. 

MOUSE_BN1_DOWN Button-1-down event. 

MOUSE_MOTION_WITH_BN2_.DOWN Mouse motion with button-2-down 
event. 

MOUSE_BN2_DOWN ' Button-2-down event. 

MOUSE_MOTION_WITH_BN3_DOWN Mouse motion with button-3-down 
event. 

MOUSE_BN3_DOWN Button-3-down event. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 
Button 1 is the left button on the mouse. 


This example creates a mouse handle, calls the MouGetEventMask function, 
and checks the event mask to see if events are accepted from a third button on 
the mouse: 


HMOU hmou; 
USHORT fsEvents; 


' MouOpen(OL, &hmou) ; 


See Also 


MouGetEventMask (&fsEvents, hmou) ; 
if(fsEvents & (MOUSE_MOTION_WITH_BN3_DOWN | MOUSE_BN3_DOWN) 
VioWrtTTY("Three buttons enabled\n\r", 23, O); 


MouOpen, MouReadEventQue, MouSetEventMask 
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H@ MouGetNumButtons 


USHORT MouGetNumButtons(pusButtons, hmou) 
PUSHORT pusButtons; /s pointer to variable for number of mouse buttons «/ 
HMOU hmou; — _ /« mouse handle »/ 


The MouGetNumButtons function retrieves the number of buttons on the 
current mouse. 


Parameters pusButtons Points to the variable that receives the number of buttons on the 
mouse. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


Example This example creates a mouse handle then calls the MouGetNumButtons func- 
tion to retrieve the number of mouse buttons: 
HMOU hmou; 
USHORT usButtons; 
MouOpen (OL, &hmou) ; 
MouGetNumButtons (&usButtons, hmou) ; 
if(usButtons == 
VioWrtTTY ("Your mouse has two buttons\n\r", 28, 0); 


See Also MouOpen 


@ MouGetNumMickeys 


USHORT MouGetNumMickeys (pusMickeys, hmou) 
PUSHORT pusMickeys; /s pointer to variable for mickeys per centimeter «/ 
HMOU hmou; /« mouse handle »/ 


The MouGetNumMickeys function retrieves the number of mickeys that the 
specified mouse travels for each centimeter of motion. A mickey is the smallest 
unit of motion.a mouse can measure. The number of mickeys per centimeter for 
a mouse depends on the device and may also depend on the current setting of » 
the device. . 


Parameters pusMickeys Points to the variable that receives the number of mickeys per 
centimeter. | 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 
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Example 


See Also 


This example creates a mouse handle then calls the MouGetNumMickeys func- 
tion to retrieve the current number of mickeys per centimeter: 

HMOU hmou; 

USHORT usMickeys; 


MouOpen (OL, &hmou) ; 
MouGetNumMickeys (&usMickeys, hmou) ; 


MouOpen 


MouGetNumQueE! : 


USHORT MouGetNumQueEl(pmouqi, hmou) 
PMOUQUEINFO pmoudi; /« pointer to structure for number of events «/ 


HMOU hmou; 


Parameters 


Return Value 


Example 


See Also 


/»x mouse handle x/ 


The MouGetNumQueEl function retrieves the number of events in the mouse 
event queue. 


pmouqi Points to the MOUQUEINFO structure that receives the number of 
events in the mouse event queue. The MOUQUEINFO structure has the follow- 
ing form: 
typedef struct _MOUQUEINFO { 

USHORT cEvents; 


USHORT cmaxEvents; 
} MOUQUEINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle, enables the mouse pointer to be drawn, 
and runs within an infinite for loop until there are no events in the queue: 


HMOU hmou; 

MOUEVENTINFO mouevEvent; 
MOUQUEINFO mouqi; 

USHORT fWait = FALSE; 
MouOpen(OL, &hmou) ; 
MouDrawPtr (hmou) ;: 


for (;:) 
MouGetNumQueEl1 (&mouqi, /* retrieves queue */ 
hmou; 
if (mouqi.cEvents > 1) /* until the last queue... */ 
MouReadEventQue (&mouevEvent, &fWait, hmou) ; 
else 
break; 
} 


MouFlushQue, MouOpen, MouReadEventQue 
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@ MouGetPtrPos 


USHORT MouGetPtrPos(pmoup!/Position, hmou) 
PPTRLOC pmoup)i; /« pointer to structure for current mouse position »/ 
HMOU hmou; — /» mouse handle »/ 


The MouGetPtrPos function retrieves the current position of the mouse device. 
This position is given in screen coordinates. 


Parameters pmoupl Points to the PTRLOC structure that receives the coordinates of the 
mouse position. The PTRLOC structure has the following form: 


typedef struct _PTRLOC { 
USHORT row; 
USHORT col; 

} PTRLOC; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hmou Identifies the mouse. The naudle must have been created previously by 
using the MouOpen function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


Comments The current device status as defined by the MouSetDevStatus function does not 
affect the row and col fields of the PTRLOC structure. These fields always 
specify an absolute position relative to the upper-left corner of the screen. 


Example This example creates a mouse handle and enables the mouse pointer to be 
drawn. It then displays the text “Place mouse here” at the top of the screen and 
repeatedly calls the MouGetPtrPos function until the mouse is moved over the 
text: 


PTRLOC moupl1; 

HMOU hmou; 

BYTE bAttr = 0x72; /* green character on white background */ 
MouOpen(OL, &hmou) ; ; : 
MouDrawPtr (hmov) ; 
VioWrtCharStrAtt ("Place mouse here", 16, 0, 35, &bAttr, O); 


do 
MouGetPtrPos(&moupl, hmou) ; 
while (moupl.row != O || (moupl.col < 35 || moupl.col > 50)); 
See Also MouOpen, MouSetDevStatus, MouSetPtrPos 


H@ MouGetPtrShape 
USHORT MouGetPtrShape ( pbBuffer, pmoupsinfo, hmou) 


PBYTE pbBuffer; /« pointer to buffer for shape masks »/ 
PPTRSHAPE pmoupsinfo; /« pointer to structure for shape. information «/ 


HMOU hmou; _ /* mouse handle / 


The MouGetPtrShape function retrieves the AND and XOR masks that define 
the shape of the pointer for the specified mouse. MouGetPtrShape also retrieves 
information about the pointer, such as the width and height of masks and the 
location of the hot spot. 
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Parameters 


Return Value 


Comments 


Example 


See Also 


pbBuffer Points to the buffer that receives the masks. 
pmoupsInfo Points to the PTRSHAPE structure that receives the pointer 


information. The PTRSHAPE structure has the following form: 


typedef struct _PTRSHAPE { 
‘USHORT cb; 
USHORT col; 
USHORT row; 
USHORT colHot; 
USHORT rowHot; 
} PTRSHAPE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” - 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


The MouGetPtrShape function copies the AND and XOR masks to the buffer 
pointed to by the pbBuffer parameter. The format and size of the masks depend 
on the display device and the video mode. In text mode, each mask is typically a 
character/attribute pair. In graphics mode, each mask is a bitmap. 


The MouGetPtrShape function copies information about the pointer to the 
structure pointed to by the pmoupsInfo parameter. This structure defines the - 
length (in bytes) of the AND and XOR masks, the width and height of each 
mask, and the offset from the current mouse position (or hot spot) to the 
upper-left corner of the pointer shape. 


Before calling MouGetPtrShape, you must set the cb field of the PTRSHAPE 
structure to the appropriate buffer size. If the field does not specify an appropri- 
ate size, the function copies the current size to the field and returns an error 
without copying the masks to the specified buffer. 


This example creates a mouse handle, draws the mouse pointer, and calls the 
MouGetPtrShape function to retrieve the shape of the mouse pointer: 


PTRSHAPE moupsInfo; 

BYTE abBuffer [4]; 

HMOU hmou; 

MouOpen(OL, &hmou) ; 

MouDrawPtr (hmov) ; 

moupsInfo.cb = sizeof (abBuffer) ; 
MouGetPtrShape(abBuffer, &moupsInfo, hmou) ; 


MouOpen, MouSetPtrShape. 
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M@ MouGetScaleFact 


USHORT MouGetScaleFact(pmouscFactors, hmou) 
PSCALEFACT pmouscFactors; /« pointer to structure for scaling factors «/ 


HMOU hmou; 


Parameters 


Return Value 


Example 


See Also 


M MoulnitReal 


/« mouse handle s/ 


The MouGetScaleFact function retrieves the horizontal and vertical scaling fac- 
tors for the specified mouse. The scaling factors define the number of mickeys 
the mouse must travel horizontally or vertically in order to cause MS OS/2 to 
move the mouse pointer one screen unit. 
pmouscFactors Points to the SCALEFACT structure that receives the scaling 
factors. The SCALEFACT structure has the following form: 
typedef struct _SCALEFACT { 

USHORT rowScale; 


USHORT colScale; 
} SCALEFACT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle then calls the MouGetScaleFact function 
to retrieve the scaling factors for the row and column coordinates: 


SCALEFACT mouscFactors; 


HMOU hmou; 
MouOpen(OL, &hmou) ; 
MouGetScaleFact (&mouscFactors, hmou); /* retrieves scaling factors */ 


MouGetNumMickeys, MouOpen, MouSetScaleFact 


USHORT MoulinitReal(pszDriverName) 


PSZ pszDriverName; 


Parameters 


Return Value 


/« pointer to string for name of mouse device driver »/ 


The MoulnitReal function loads and initializes the real-mode mouse device 
driver pointed to by the pszDriverName parameter. You must specify the name 
of the mouse device driver by using a device command in the config.sys file. 


This function is used only by the Task Manager. 
pszDriverName Points to the null-terminated string that specifies the name of 


the mouse device driver. The name must be a valid filename. You can initialize 
the default mouse device driver by setting this parameter to zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


190 MouinitReal 


Comments 


See Also 


MouOpen 


The Mou functions are not available in real-mode programs. Instead, all real- 
mode mouse input and output must be carried out using the real-mode (int 33h) 
interface. 


- MouOpen 


USHORT MouOpen( pszDriverName, phmou) 


PSZ pszDriverName; 


PHMOU phmou; 


Parameters 


Return Value 


Example 


See Also 


/x pointer to mouse driver name x/ 
/x pointer to variable for mouse handle «/ 


The MouOpen function opens the mouse for the current screen group and 
creates a handle that can be used in subsequent Mou functions (to display the 
mouse pointer, retrieve the current location of the mouse pointer, etc.). 


The MouOpen function creates the mouse handle for the current screen group 
only. Any number of processes may open this handle, but all processes in the 
screen group share it. For example, if one process changes the color of the 
mouse pointer, the pointer color changes for all other processes in the same 
screen group. 


When the mouse handle is first created, MouOpen does not display the mouse 
pointer. The MouDrawPtr function must be called to display the pointer. (A 
mouse device driver is required to draw the pointer. If the mouse device driver 
pointed by the pszDriverName parameter does not exist or cannot be opened, an 
error occurs and the pointer is not drawn. If pszDriverName is set to zero, the 
default mouse device driver is used; that is, the driver specified in a device com- 
mand in the config.sys file is used.) 


pszDriverName Points to the null-terminated string that contains the name of 
the mouse device driver. The name must be a valid filename. If this parameter is 
set to zero, the default pointer-draw driver is used. 


phmou Points to-the variable that receives the mouse handle. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_MODULE 
ERROR_MOUSE_NO_DEVICE 


This example calls the MouOpen function to create a mouse handle to be used 
by the current screen group: 


HMOU hmou; 
MouOpen(OL, &hmou) ; 


MouClose, MouDrawPtr 
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M@ MouReadEventQue 


USHORT MouReadEventQue (pmouevEvent, pfWait, hmou) 
PMOUEVENTINFO pmouevEvent; /« pointer to structure for mouse event «/ 


PUSHORT pfWait; 


HMOU hmou; 


Parameters 


Return Value 


Comments 


/« wait/no-wait flag »/ 
/«{ mouse handle »/ 


The MouReadEventQue function retrieves a mouse event from the event queue 
of the specified mouse. The event queue is a buffer to which MS OS/2 copies 
each mouse event. A mouse event is a structure that specifies the user action 
that generated the event, the location of the mouse when the event occurred, 
and system time when the event occurred. 


MS OS/2 copies a mouse event to the event queue whenever the user moves the 
mouse or presses or releases a mouse button. The mouse event can specify a sin- 
gle action or a combination of actions, such as the mouse being moved with a 
button down. MS OS/2 copies a mouse event for a given action only if the event 
mask enables reporting for that action. For more information, see the MouSet- 
EventMask function. 


pmouevEvent Points to the MOUEVENTINFO structure that receives the 
mouse event. The MOUEVENTINFO structure has the following form: 
typedef struct _MOUEVENTINFO { 

USHORT fs; 

ULONG time; 

USHORT row; 

USHORT col; 
} MOUEVENTINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pfWait Points to the variable that specifies whether the function waits for an 
event. If this parameter is MOU_NOWAIT and the queue is empty, the function 
fills the MOUEVENTINEO structure with zeros and returns immediately. If the 
parameter is MOU_WAIT, the function waits for a mouse event if none is avail- 
able. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 
NO_ERROR_MOUSE_NO_DATA 


Button 1 is the left button on the mouse. 


The meaning of the row and col fields of the MOUEVENTINFO structure 
depends on the current device status as defined by the most recently used 
MouSetDevStatus function. The values may be absolute or relative, and the 
units may be mickeys, character cells, or pels. 


Although a specific action may not generate a mouse event, the fs field of the 
MOUEVENTINFO structure may include information about the action when 
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some other event occurs. For example, even if button 2 is disabled, fs is set to 
0x0014 if the user presses button 1 when button 2 is also down. If the pfWait 
parameter is MOU_LNOWATT, fs will be zero if cither a mouse-button-up event 
occurs or no event occurs. To see whether an event occurred, check the time 
field; it will be zero if there was no event. 


Example This example creates a mouse handle, enables the mouse pointer to be drawn, 
and calls the MouReadEventQue function, telling it to wait until a mouse event 
occurs. If the mouse event is the left mouse button down, the message “Left 
Button” is displayed: 

MOUEVENTINFO mouevEvent ; 

HMOU hmou; 

USHORT fWait = TRUE; /* waits for mouse event */ 
MouOpen (OL, &hmou) ; 

MouDrawPtr (hmou) ; 

MouReadEventQue (&mouevEvent, &fWait, hmou) ; 


if (mouevEvent.fs & Ox04) /* if left button pressed... */ 
VioWrtTTY ("Left Button\n\r", 13, 0); 


See Also MouGetNumQueE!, MouOpen, MouSetDevStatus, MouSetEventMask 


MouRegister 


USHORT MouRegister( pszModuleName, pszEntryName, flFunctions) 
PSZ pszModuleName; /« pointer to string for module name «/ 
PSZ pszEntryName; /» pointer to string for entry name — +/ 
ULONG fiFunctions; /« function flags »/ 


The MouRegister function registers a Mou subsystem for the specified mouse. 
The function temporarily replaces the one (or more) default Mou functions, as 
specified by the flFunctions parameter, with the functions in the module pointed 
to by the pszModuleName parameter. Once MouRegister replaces a function, 
MS OS/2 passes any subsequent calls to the replaced function to a function in 
the given module. If you do not replace a function, MS OS/2 continues to call 
the default Mou function. 


Parameters pszModuleName Points to the null-terminated string that contains the name 
of the dynamic-link module containing the replacement Mou functions. 


pszEntryName Points to the null-terminated string that contains the dynamic- 
link entry-point name of the function that replaces the specified Mou function. 
For a full description, see the following “Comments” section. 


flFunctions Specifies the flags of the Mou functions to replace. It can be any 
combination of the following values: 


Value Meaning 
-MR_MOUGETNUMBUTTONS Replace MouGetNumButtons. 
MR_MOUGETNUMMICKEYS Replace MouGetNumMickeys. 
MR_MOUGETDEVSTATUS Replace MouGetDevStatus. 
MR_MOUGETNUMQUEEL Replace MouGetNumQueE!l. 
MR_MOUREADEVENTOQUE _ Replace MouReadEventQue. 


Return Value 


Comments 


Value 


MR_MOUGETSCALEFACT 
MR_MOUGETEVENTMASK 
MR_MOUSETSCALEFACT 
MR_MOUSETEVENTMASK 
MR_MOUOPEN 
MR_MOUCLOSE 
MR_MOUGETPTRSHAPE 
MR_MOUSETPTRSHAPE 
MR_MOUDRAWPTR 
MR_MOUREMOVEPTR 
MR_MOUGETPTRPOS 
MR_MOUSETPTRPOS 
MR_MOUINITREAL 
MR_MOUSETDEVSTATUS 


MouRegister 


Replace MouGetScaleFact. 
Replace MouGetEventMask. 
Replace MouSetScaleFact. 
Replace MouSetEventMask. 
Replace MouOpen. 

Replace MouClose. 

Replace MouGetPtrShape. 
Replace MouSetPtrShape. 
Replace MouDrawPtr. 
Replace MouRemovePtr. 
Replace MouGetPtrPos. 
Replace MouSetPtrPos. 
Replace MoulnitReal. 
Replace MouSetDevStatus. 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INVALID_ASCIIZ 


ERROR_MOUSE_INVALID_MASK 
ERROR_MOUSE_REGISTER | 


MS OS/2 passes a Mou function to the given module by preparing the stack and 
calling the function pointed to by the pszEntryName parameter. Specified 
module must export the entry-point function name. The entry-point function 
must check the function code on the stack to determine which function is being 
requested, then pass control to the appropriate function in the module. The 
entry-point function may then access any additional parameters placed on the 
stack by the MouRegister function: 


Only one process in a screen group may use the MouRegister function at any 
given time. That is, only one process at a time can replace Mou functions. The 
process can restore the default Mou functions by calling the MouDeRegister 
function. A process can replace a Mou function any number of times, but only 
by first restoring the default functions and then reregistering the new functions. 


The entry-point function (FuncName) must have the following form: 


SHORT FAR FuncName(usReserved1, usFunction, ulReserved2, 
usParaml1, usParam2, usParam3, usParam4, usParam5) 

USHORT usReserved 1; 3 

USHORT us Function; 

ULONG ulReserved2; 

USHORT usParam1; 

USHORT usParam2; 

USHORT usParam3; 

USHORT usParam4; 

USHORT usParam5; 
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Parameter Description 


usReserved1 Specifies a reserved value that must not be changed. 
This value represents a return address for the MS OS/2 
function that routes Mou function calls. 


usFunction Specifies the function code that identifies the function 
request. It can be one of the following values: 
Value Meaning 
0x0000 MouGetNumButtons called. 
0x0001 MouGetNumMickeys called. 
0x0002 MouGetDevStatus called. 
0x0003 MouGetNumQuekEl called. 
0x0004 MouReadEventQue called. 
0x0005 MouGetScaleFact called. 
0x0006 MouGetEventMask called. 
0x0007 MouSetScaleFact called. 
0x0008 MouSetEventMask called. 
0x0009 MouGetHotKey called. 
Ox000A MouSetHotKey called. 
0x000B MouOpen called. 
0x000C MouClose called. 
0x000D MouGetPtrShape called. 
Ox000B. MouSetPtrShape called. 
0x000F MouDrawPtr called. 
0x0010 MouRemovePtr called. 
0x0011 MouGetPtrPos called. 
0x0012- MouSetPtrPos called. 
0x0013 MoulnitReal called. 
0x0014 MouFlushQue called. 
0x0015 MouSetDevStatus called. 
ulReserved2 Specifies a reserved value that must not be changed. 


This value represents the return address of the program 
that calls the specified Mou function. 


usParam1-usParam5 Specifies up to five values passed with the original Mou 
function call. The actual number and type of parame- 
ters used depend on the specific function. 


The registered function should return - 1 if it wants the original funcdon called, 
0 if no error occurred, or an error value. 


The entry-point function should determine which function is requested and then 
carry out an appropriate action using the passed parameters. If necessary, the 
entry-point function can call a replacement function within the given module to 


See Also 


MouRemovePtr 
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carry out the task. The entry-point or replacement function must Hieave the stack 
in the same state it was received. This is required since the return addresses on 
the stack must be available in the correct order to return control to the program 
that originally called the MouRegister function. 


In general, if the replacement function needs to-access the mouse, it must use 
the input-and-output control functions for the mouse. For more information, see 
Chapter 3, “Input-and-Output Control Functions.” 


The MouRéegister function itself cannot be replaced. 


MouDeRegister 


USHORT MouRemovePtr(pmourtRect, hiiou) 
PNOPTRRECT pmourtRect; /« pointer to structure with exclusion rectangle «/ 


HMOU hmou; 


Parameters 


Return Value 


Comments 


/« mouse handie «/ 


The MouRemovePtr function removes the mouse pointer from a portion of the 
screen or from the entire screen. This part of the screen is called an exclusion 
rectangle, because when the mouse pointer moves into it, the pointer 
disappears—it is still present and can be moved, but it will not appear until it is 
moved out of the exclusion rectangle. If the pointer is outside the exclusion rec- 
tangle and is not currently displayed, MS OS/2 draws the mouse pointer. 


The MouRemovePtr function ay be called by any process in the screen group. 
Only one exclusion rectangle is active at a time, so each call to the function 
replaces the previous rectangle. The MouDrawPtr function removes the exclu- 
sion rectangle completely. 


pmourtRect Points to the NOPTRRECT structure that contains the coordi- 
nates of the exclusion rectangle. The NOPTRRECT structure has the following 
form: 
typedef struct _NOPTRRECT { 

USHORT row; 

USHORT col; 

USHORT cRow; 


USHORT cCol; 
} NOPTRRECT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


You should exclude the mouse pointer from any portion of the screen that is 
likely to change, such as a text-entry field. When you position the mouse pointer, 
MS OS/2 saves the character beneath it; when you move the mouse again, 
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MS OS/2 restores the character. If the character changed between the time you 
positioned the mouse and the time you moved it, the new character is lost when 


MS OS/2 restores the old characier. 


Example This example creates. a mouse handle and enables the mouse pointer to be 
drawn. It then defines an exclusion rectangle in the center of the screen and calls 
the MouRemovePtr function to notify the mouse device driver that this rectangle 
is for the exclusive use of the process. When you move the mouse pointer into 
this rectangle, the pointer disappears: 
NOPTRRECT mourtRect; 
HMOU hmou; 
MouOpen (OL, &hmou) ; 
MouDrawPtr (hmou) ; 
mourtRect.row = 6; 
mourtRect.col = 30; /* upper-left y-coordinate */ 
mourtRect.cRow = 18; /* lower-right x-coordinate */ 
mourtRect.cCol = 50; /* lower-right y-coordinate * 
MouRemovePtr (&mourtRect, hmou) ; 

See Also MouDrawPtr, MouOpen, MouSetPtrShape 

MouSetDevStatus 


USHORT MouSetDevStatus(pfsDevStatus, hmou) 
PUSHORT pfsDevStatus; _—/« pointer to buffer with status «/ 


HMOU hmou; 


Parameters 


Return Value 


Comments 


/» mouse handle »/ 


The MouSetDevStatus function sets the device status for the specified mouse. 
The device status enables or disables the mouse device driver and defines 
whether the mouse position is reported in mickeys or in screen units (character 
cells or pels). 


pfsDevStatus Points to the variable that contains the device status to be set. 
This parameter can be any combination of the following values: 


Value Meaning 


MOUSE_DISABLED Disable the default mouse device driver. If this value is 
not given, the function enables the mouse device 
driver. 


MOUSE_MICKEYS _ Report mouse motion in mickeys; that is, MS OS/2 
reports motion as a number of mickeys moved from the 
last-reported position. If the value is not given, MS 
OS/2 reports mouse motion in screen units relative to 
the upper-left corner of the screen. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


The MouSetDevStatus function enables or disables the mouse device driver. 
When this device driver is enabled, it draws the pointer by combining the AND 


~ and XOR masks of the pointer shape with the contents of the screen at the 
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current mouse location. It draws the pointer whenever the mouse moves (or 
when an interrupt associated with the mouse occurs). When the mouse device 
driver is disabled, the function does not draw the pointer. In such cases, the 
process must draw the pointer for itself. 


The MouSetDevStatus function also directs the mouse to report relative or abso- 
lute positions. If the device is set to report absolute positions, the x- and y- 
coordinates given for a mouse position are in screen units relative to the upper- 
left corner of the screen. The type of unit depends on the screen mode. In text 
mode, the position is given in character cells; in graphics mode, the position is 
given in pels. Screen coordinates increase from left to right on the x-axis and 
from top to bottom on the y-axis. If the device is set to report relative positions, 
the x- and y-coordinates for a mouse position are given in mickeys and are rela- 
tive to the most recently reported position. In this case, the coordinates are 
signed values, defining both the direction and distance of the move. The x- 
coordinate is negative when the mouse moves left; the y-coordinate is negative 
when the mouse moves up. 


Example This example creates a mouse handle then calls the MouGetDevStatus function 
to set the device status so that mouse-movement information is returned in terms 
of mickeys, not pels. This allows the process to obtain mouse information in 
terms of relative movement rather than in terms of absolute pel position: 


USHORT fsDevStatus = 0x0200; /* returns mickeys */ 
HMOU hmou; 
MouOpen(OL, &hmou) ; 
MouSetDevStatus (&fsDevStatus, hmou) ; /* sets device status */ 
See Also MouGetDevStatus, MouOpen 
MouSetEventMask 


USHORT MouSetEventMask( pfsEvents, hmou) 
PUSHORT pfsEvents; /« pointer to buffer with event mask «/ 
HMOU hmou; /x mouse handle »/ 


The MouSetEventMask function sets the event mask for the specified mouse. 
The event mask defines the user actions that generate mouse events (movement 
or pressing or releasing a button). 


The MouSetEventMask function enables or disables specific user actions. When 
an action is enabled, MS OS/2 copies a mouse event to the event queue when- 
ever the user carries out the action. When an action is disabled, no mouse event 
is copied. 


Parameters pfsEvents Points to the variable that contains the event mask. The variable 
can be any combination of the following values: 


Value Meaning 


MOUSE_MOTION Enable mouse motion with no- 
buttons-down event. 


MOUSE_MOTION_WITH_BN1i_DOWN ~ Enable mouse motion with button- 
1-down event. 
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Return Value 


Comments 
Example 


See Also 


MouSetPtrPos 


Value Meaning 


MOUSE_BN1 DOWN Enable button-i-down event. 


MOUSE_MOTION_WITH_BN2_DOWN _ Enable mouse motion with button- 
2-down event. 
MOUSE_BN2_DOWN Enable button-2-down event. 
MOUSE_MOTION_WITH_BN3_DOWN _— Enable mouse motion with button- 
3-down event. 
MOUSE_BN3_DOWN Enable button-3-down event. 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


Button 1 is the left button on the mouse. 


This example creates a mouse handle then calls the MouSetEventMask function 
to set the event mask so that only the mouse motion or the pressing of the left 
button are recognized by the MouReadEventQue function: 

USHORT fsEvents; 


HMOU hmou; 
MouOpen (OL, &hmou) ; 


/* detect motion and button 1 */ 
fsEvents = MOUSE_MOTION | 


MOUSE_MOTION_WITH_BN1_DOWN | MOUSE_MOTION_WITH_BN1_DOWN; 
MouSetEventMask (&fsEvents, hmou); 


MouGetEventMask, MouOpen, MouReadEventQue 


USHORT MouSetPtrPos(pmoup/Position, hmou) 
PPTRLOC pmoup/Position; /« pointer to structure for new mouse position »/ 


HMOU hmou; 


/« mouse handle »/ 


The MouSetPtrPos function sets the current mouse position to the position 
pointed to by the pmouplPosition parameter. If the pointer is visible, the func- 
tion moves the mouse pointer to the new location on the screen. The new posi- 


tion is always in screen units and is relative to the upper-left corner of the 
screen. 


Parameters 


Return Value 
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pmouplPosition Points to the PTRLOC structure that contains the new mouse 
position. The PTRLOC structure has the following form: 
typedef struct _PTRLOC { 

USHORT row; 


USHORT col; 
} PTRLOC; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


Comments MS OS/2 hides the pointer if the new position is in the exclusion rectangle 
defined by the most recent call to the MouRemovePtr function. 

Example This example creates a mouse handle and calls the MouSetPtrPos function to 
initialize the mouse pointer in the upper-left corner of the screen. It then calls 
the MouDrawPtr function to enable the mouse pointer to be drawn: 

PTRLOC moup1l1Position; 
HMOU hmou; 
MouOpen (OL, &hmou) ; 
mouplPosition.row = 0; /* row zero */ 
mouplPosition.col = 0; /* column zero * 
MouSetPtrPos (&moup1lPosition, hmou) ; /* sets mouse position */ 
MouDrawPtr (hmou) ; 
See Also MouDrawPtr, MouGetPtrPos, MouOpen, MouRemovePtr 
MouSetPtrShape 


USHORT MouSetPtrShape ( pbBuffer, pmoupsinfo, hmou) 


PBYTE pbBuffer; 


/« pointer to buffer with shape masks «/ 


PPTRSHAPE pmoupsinfo; / pointer to structure with shape info. »/ 


HMOU hmou; 


Parameters 


/« mouse handle x/ 


The MouSetPtrShape function sets the AND and XOR masks that define the 
shape of the mouse pointer for the specified mouse. MouSetPtrShape also sets 
information about the pointer, such as the width and height of masks and the 
location of the hot spot. 


pbBuffer Points to the buffer that contains the new masks. 


pmoupsInfo Points to the PTRSHAPE structure that contains the new pointer 
information. The PTRSHAPE structure has the following form: 


typedef struct _PTRSHAPE { 
USHORT cb; 
USHORT col; 
USHORT row; 
USHORT colHot; 
USHORT rowHot; 
} PTRSHAPE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


Comments 


See Also 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_NO_DEVICE 


The MouSetPtrShape function copies the AND and XOR masks from the buffer 
pointed to by the pbBuffer parameter. The format and size of the masks depend 
on the display device and the video mode. In text mode, each mask is typically a 
character/attribute pair. In graphics mode, each mask is a bitmap. 


The MouSetPtrShape function copies information about the pointer from the 
structure pointed to by the pmoupsInfo parameter. The structure defines the 
length (in bytes) of the AND and XOR masks, the width and height of each 
mask, and the offset from the current mouse position (or hot spot) to the 
upper-left corner of the pointer. 


If the pointer is displayed, the MouSetPtrShape function may not display a 
new shape immediately. If the pointer is not displayed, you must use the 
MouRemovePtr and MouDrawPtr functions to display the new shape. 


The pointer shape is dependent on the device driver used to support the display 
device. In text mode, MS OS/2 supports the pointer shape as a reverse block 
character. This character has a one-character height and width; that is, in text 
modes, the height and width fields must each be one. You can determine the 
current pointer shape in effect for the screen group by using the MouGetPtr- 
Shape function. 


MouDrawPtr, MouGetPtrShape, MouOpen, MouRemovePtr 


MouSetScaleFact 


USHORT MouSetScaleFact(pmouscFactors, hmou) 
PSCALEFACT pmouscFactors; /« pointer to structure for scaling factors »/ 


HMOU hmou; 


Parameters 


/« mouse handle x/ 


The MouSetScaleFact function sets the horizontal and vertical scaling factors for 
the specified mouse. The scaling factors define the number of mickeys the mouse 
must travel horizontally or vertically to cause MS OS/2 to move the mouse 
pointer one screen unit. 


pmouscFactors Points to the SCALEFACT structure that contains the scaling 
factors. The SCALEFACT structure has the following form: 
typedef struct _SCALEFACT { 

USHORT rowScale; 


USHORT .colScale; 
} SCALEFACT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hmou Identifies the mouse. The handle must have been created previously by 
using the MouOpen function. 


Return Value 


Example 


See Also 


MouSynch 
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The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_MOUSE_NO_DEVICE 


This example creates a mouse handle, enables the mouse pointer to be drawn, 
and retrieves the current scaling factor. It then doubles the scaling factor and 
calls the MouSetScaleFact function to set the new factor. The result is that you 
must move the mouse twice as far in order to move the pointer on the screen: 
SCALEFACT mouscFactors; 

HMOU hmou; 


MouOpen(OL, &hmou) ; 
MouDrawPtr (hmou) ; 


MouGetScaleFact (&mouscFactors, /* retrieves scaling factors */ 
hmou) ; 

mouscFactors.rowScale *= 2; /* vertical scaling factor */ 

mouscFactors.colScale *= 2; /* horizontal scaling factor */ 

MouSetScaleFact (&mouscFactors, /* sets new scaling factors */ 
hmou) ; 


MouGetScaleFact, MouOpen 


USHORT MouSynch( fWait) 


USHORT fWait: 


Parameters 


Return Value 


Comments 


See Also 


/« wait/no-wait flag «/ 


The MouSynch function synchronizes access to the mouse. This function should 
be used by a Mou subsystem to prevent more than one process from accessing 
the mouse handle at any one time. 


fWait Specifies whether to wait if the mouse device driver is currently busy. If 
this parameter is FALSE, the function returns control immediately without wait- 
ing for the device to become free. If the parameter is TRUE, the function waits 
until the mouse handle is free. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


The MouSynch function requests an exclusive system semaphore that clears 
when the Mou subsystem returns to the mouse router. The MouSynch function 
blocks all other threads within a screen group until the semaphore clears. 


DosCloseSem, DosDevIOCtl, MouRegister 
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™ VioAssociate 


USHORT VioAssociate (hdc, hvps) 
HDC hdc; /« device-context handle »/ 
HVPS hvps; _—/« presentation-space handle «/ 


Parameters 


Return Value 


See Also 


The VioAssociate function associates an advanced video-input-and-output 
(AVIO) presentation space. with a device context. Subsequent calls to the 
VioShowPS and VioShowBuf functions direct output to this device context. 


A screen device context is the only kind of device context that may be associ- 
ated with an AVIO presentation space. If the AVIO presentation space is 
currently associated with another device context, it is disassociated. Similarly, 
if another AVIO presentation space is currently associated with the device 
context, it too is disassociated. 


If you specify a NULL handle for the device context, the presentation space is 
disassociated from the currently associated device context. 

hdc _ Identifies the device context to associate with the presentation space. If 
this parameter is NULL, the function disasssociates the previous device context. 
hvps Identifies the AVIO presentation space. The space must have been 
created previously by using the VioCreatePS function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


VioCreatePS, VioShowBuf, VioShowPS, WinOpenWindowDC 
a VioCreateLogFont 
USHORT VioCreateLogFont(pfat, Icid, pstr8Name, hvps) 
PFATTRS pfat; /« pointer to structure for font attributes »/ 
LONG Icid; /+ local identifier for font »/ 
PSTR8 psir8Name; /« pointer to descriptive name of logical font «/ 
HVPS hvps; /« presentation-space handle »/ 


The VioCreateLogFont function creates a logical font for the given. advanced 
video-input-and-output (AVIO) presentation space. A logical font is a list of 
attributes, such as character size and weight, that specifies the font used for 
writing text. When a font is needed, MS OS/2 chooses from the available physi- 
cal fonts the one that most closely matches the logical font. A program may, 
however, force selection of a particular font by setting the IMatch field in the 
FATTRS structure to the value returned for the requested font by the 
VioQueryFonts function. 


If the szFaceName field in the FATTRS structure is NULL and all of the attri- 
butes except the code page are set to zero, the system default font is selected, in 
the specified code page. 


Parameters 


Return Value 


See Also 


™ VioCreatePS | 
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pfat Points to the FATTRS structure that contains the attributes of the font. 
The FATTRS structure has the following form: 


typedef struct _FATTRS { 


USHORT usRecordLength; 
USHORT fsSelection; 
LONG 1Match; 
CHAR  szFaceName[FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 
LONG 1MaxBaselineExt; 
LONG lAveCharWidth; 
USHORT usWidthClass; 
USHORT usWeightClass; 
USHORT fsType; 
SHORT sQuality; 
USHORT fsFontUse; 

} FATTRS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Icid Specifies the local identifier for the font. This parameter must be 1, 2, or 
3. If the identifier is already being used to refer to a font or bitmap, the function 
returns an error. 


pstr8Name Points to an 8-character name that you may use to describe the 
logical font. 


hyps Identifies the AVIO presentation space. This presentation space must 
have been created previously by using the VioCreatePS function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, indicating that an error occurred. 


VioQueryFonts 


USHORT VioCreatePS( phvps, cRows, cColumns, fFormat, cAttrBytes, hvps) 


PHVPS phvps; 
SHORT cRows; 
SHORT cColumns; 
SHORT fFormat; 
SHORT cAtirBytes; 
HVPS hvps; 


Parameters 


/« pointer to variable for presentation-space handle «/ 


/x height of presentation space x/ 
/« width of presentation space »/ 
/« format of attribute byte(s) »/ 
/« number of attributes »/ 
/« presentation-space handle x/ 


The VioCreatePS function creates an advanced video-input-and-output (AVIO) 
presentation space, the size of which must not exceed 32K. To determine the 
size of the presentation space, multiply the cColumns, cRows, and cAttrBytes 
parameters as follows: cColumns x cRows xX (cAttrBytes + 1). 


phvps Points to the variable that receives the presentation-space handle. You 
may use this handle in subsequent Vio functions. 
cRows Specifies the height (in character cells) of the presentation space. 


cColumns Specifies the width (in character cells) of the presentation space. 
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Return Value 


See Also 


VioDeleteSetid 


fFormat Identifies the format of the attribute byte(s) in the presentation 
space. The content of the attribute bytes depends on the format. Currently, the 
only defined format is zero. If the format is zero, the atiribute bytes have the fol- 
lowing meanings: 

Value Meaning 


FORMAT_CGA Specifies a CGA format of two attribute bytes. The first 
byte contains the character value. The second byte con- 
tains bit fields that specify the background and fore- 
ground colors. Blink and intensity fields are not sup- 
ported. , 


FORMAT_4BYTE Specifies an extended format of four attribute bytes. 
The first byte contains the character value. The second 
byte contains bit fields that specify the background and 
foreground colors. The third byte contains bit fields 
that specify the underscore, reverse video, the back- 
ground opacity, and the font identifier. The fourth byte 
is an extra byte to be used by programs. 


cAttrBytes Specifies the number of attribute bytes per character cell in the 
presentation space. This number may be 1 or 3. 


hvps Identifies the AVIO presentation space. This parameter must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


VioDestroyPS 


USHORT VioDeleteSetld(/cid, hvps) 
LONG /cid; /« local identifier for object «/ 
HVPS hvps; /» presentation-space handle «/ 


Parameters 


Return Value 


See Also 


The VioDeleteSetId function deletes the logical font specified by the Icid param- 
eter. Do not use this function to delete the object specified by the local identifier 
zero. 


Icid Specifies the local identifier for the object. This parameter must be 1, 2, 
or 3. If you specify - 1, this function deletes all logical fonts. 


hvps_ Identifies the advanced video-input-and-output (A VIO) presentation 
space. This presentation space must have been created previously by using the 
VioCreatePS function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


VioCreateLogFont, VioCreatePS 
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H@ VioDeRegister 
USHORT VioDeRegister( VO/D) 


The VioDeRegister function restores the functions of the default Vio subsystem 
and releases any previously registered Vio subsystem. The function restores the 
default Vio subsystem for all processes in the current screen group. 


Once a process registers a Vio subsystem, no other process in the screen group 
may register a Vio subsystem until the default subsystem is restored. Only the 
process registering a Vio subsystem may call the VioDeRegister function to 
restore the default Vio subsystem. 


Parameters This function has no parameters. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 
ERROR_VIO_DEREGISTER 
See Also VioRegister 


—@ VioDestroyPS 


USHORT VioDestroyPS(hvps) 
HVPS hvps; /« presentation-space handle «/ 


The VioDestroyPS function destroys the specified advanced video-input-and- 
output (AVIO) presentation space. 


Parameters hvps Identifies the AVIO presentation space to destroy. This presentation 
space must have been created previously by using the VioCreatePS function. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
See Also VioCreatePS 


H VioEndPopUp 


USHORT VioEndPopUp(hvio) 
HVIO hvio; /« video handle »/ 


The VioEndPopUp function closes a pop-up screen and restores the physical 
video buffer to its previous contents. Only the process that opened the pop-up 
screen may close it. 


VioEndPopUp may not completely restore the screen to its previous state. For 
example, programs that modify the video registers or use graphics modes may 
have to restore the state of the registers as the pop-up screen is being closed. 
By calling the VioModeWait function, a program can request to be notified of 
the change in video mode. Whenever a process has a pending request, MS 
OS/2 notifies the process of a mode change when the pop-up screen is closed. 
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Parameters 


Return Value 


Example 


See Also 


VioGetAnsi 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_NO_POPUP 


This example creates a pop-up screen, displays a message, waits three seconds, 
then calls VioEndPopUp to close the pop-up screen: 


USHORT fWait = VP_WAIT; 


VioPopUp (&fWait, 0); /* creates Pop” up screen */ 
VioWrtTTY ("This is a VIO pop-up screen\n\r", 29, O); 

DosSleep (3000L) ; /* waits 3 seconds */ 
VioEndPopUp (0) ; /7/* ends pop-up screen */ 


VioModeWait, VioPopUp 


USHORT VioGetAnsi( pfAnsi, hvio) 


PUSHORT pfAnsi; 
HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/« pointer to variable for ANSI flag «/ 
/« video handle »/ 


The VioGetAnsi function retrieves the state of the ANSI flag, which determines 
whether the processing of ANSI escape sequences is enabled or disabled. — 


pfAnsi Points to the variable that receives the ANSI flag. If this flag is 
ANSI_ON, ANSI processing is enabled. If the flag is ANSILOFF, ANSI pro- 
cessing is disabled. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_HANDLE 


This example calls VioGetAnsi and, if ANSI processing enabled, calls the 
VioWrtTTY function to display a message: 

USHORT fAnsi; 

VioGetAnsi (&fAnsi, 0); 


if (fAnsi == ANSI_ON) 
VioWrtTTY("ANSI is on\n\r", 12, 0); 


VioSetAnsi, VioWrtT TY 


HZ VioGetBuf 
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USHORT VioGetBuf(pu/LVB, pcbLVB, hvio) 


PULONG pul/LVB; 
PUSHORT pcbLVvB; 


HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/« pointer to variable for address of LVB «/ 
/« pointer to variable for length of LVB«/ 
/« video handle «/ 


The VioGetBuf function retrieves the address of the logical video buffer (LVB), 
which contains the current character attributes for the text output of a process. 
The logical video buffer is identical in content and format to the physical video 
buffer when the process is the foreground process. The logical video buffer is 
available for text-mode screens only. 


A process can access and modify the contents of the logical video buffer at any 
time, even if the process is in the background. Changes made to the logical 
video buffer do not affect the physical screen until the process calls the Vio- 
ShowBuf function. 


The VioGetBuf function is a family API function. 


pulLVB Points to the variable that receives the address of the logical video 
buffer. 


pcbLVB Points to the variable that specifies the length (in bytes) of the logical 
video buffer. You can use the VioGetMode function to determine the dimen- 
sions of the buffer. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_HANDLE 


This example calls VioGetBuf to retrieve the address of the logical video buffer. 

It sets the character attributes in the buffer for foreground blinking by using the 

OR operator to set the high bit, then it calls the VioShowBuf function to display 
the character attributes: 

PBYTE pbLVB; 

USHORT cbLVB, i; 


VioGetBu f ( (PULONG) &pbLVB, &cbLVB, O); 
for (i = 0; i < cbLVB; i += 2 


/* OR in the high bit to make it a blinking attribute */ 


*(pbLVB + i + 1) = *(pbLVB + i + 1) | Ox80; 
VioShowBuf(O, cbLVB, 0); /* displays buffer a/ 


VioGetMode, VioGetPhysBuf, VioShowBuf 
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H VioGetConfig 


USHORT VioGetConfig( usReserved, pvioin, hvio) 


USHORT usReserved; 


/« must be zero »/ 


PVIOCONFIGINFO pvioin; /« pointer to structure for configuration «/ 


HVIO hvio; 


Parameters 


Return Value 


Comments 


Example 


See Also 


/« video handle »/ 


The VioGetConfig function retrieves the video display configuration, which 
defines the type of display adapter, the type of display, and the amount of video 
memory available. 


The VioGetConfig function is a family API function. 


usReserved Specifies a reserved value. This parameter must be zero. 


pvioin Points to the VIOCONFIGINFO structure that receives the display 
configuration for the primary display adapter. The VIOCONFIGINFO structure 
has the following form: 
typedef struct _VIOCONFIGINFO { 

USHORT cb; 

USHORT adapter; 

USHORT display; 


ULONG cbhMemory; 
} VIOCONFIGINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_LENGTH 
ERROR_VIO_LINVALID_PARMS 


MS OS/2 derives the values for the adapter and display fields for the display 
configuration by using various tests, including checking the switch settings on the 
card. 


This example calls VioGetConfig to determine whether the display type is an 
enhanced color display: 


VIOCONFIGINFO vioinConfig; 


vioinConfig.cbh = sizeof (vioinConfig) ; /7* structure length a/ 
VioGetConfig(0, /7* must be zero * 
&vioinCon fig, /* configuration data */ 
bd 


QO); /*. video handle 
if (vioinConfig.display == 2) 
VioWrtTTY ("Enhanced color display\n\r", 24, 0); 


VioGetMode, VioGetState 
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— VioGetCp 
USHORT VioGetCp(usReserved, pildCodePage, hvio) 


USHORT usReserved; /« must be zero »/ 
PUSHORT pldCodePage; /» pointer to code-page identifier «/ 
HVIO hvio; /« video handle »/ 


The VioGetCp function retrieves the identifier of the code page for the current 
screen group. This code page defines the character set being used to display text 
on the screen. If the identifier is 0x0000, the system default code page is. being 
used. Any other value identifies a code page that has been set by using the Vio- 
SetCp function or that has been inherited from the parent process. 


Parameters usReserved Specifies a reserved value. This parameter must be zero. 


pIdCodePage Points to the variable that receives the code-page identifier. The 
following are the valid code-page numbers: 


Number Code page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_HANDLE 


Example This example calls VioGetCp to retrieve the current system code page: 
USHORT idCodePage; 
VioGetCp (0, /* must be zero * 
&idCodePage, /* code-page identifier */ 
O); /* video handle 
See Also DosGetCp, DosSetCp, VioSetCp 


HB VioGetCurPos | 
USHORT VioGetCurPos(pusRow, pusColumn, hvio) 


PUSHORT pusRow; /« pointer to variable for row »/ 
PUSHORT pusColumn; /» pointer to variable for column «/ 
HVIO hvio; ‘ J/x video handle »/ 


The VioGetCurPos function retrieves the position of the cursor on the screen. 
The VioGetCurPos function is a family API function. 
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Parameters 


Return Value 


Example 


See Also 


VioGetCurType 


pusRow Points t to the variable that receives the current row position of the 
cursor. 


pusColumn Points to the variable that receives the current column position of 
the cursor. 


hvio Identifies an advanced seated (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_INVALID_HANDLE 


This example calls VioGetCurPos to retrieve the current row-and-column posi- 
tion of the cursor: 


USHORT usRow, usColumn; 


VioGetCurPos (&usRow, /* row address */ 
&usColumn, /* column address */ 
O); /* video handle s/f 


VioGetCurType, VioSetCurPos 


USHORT VioGetCurType (pviociCursor, hvio) 
PVIOCURSORINFO pviociCursor;. _/« pointer to structure for cursor info «/ 


HVIO hvio; 


Parameters 


Return Value 


/« video handle af 


The VioGetCurType function retrieves information about the cursor type. This 
information defines the height and width of the cursor, as well as whether it is 
currently visible. The VioGetCurType function is a family API function. 


pviociCursor Points to the VIOCURSORINFO structure that receives infor- 
mation about the cursor type. The VIOCURSORINFO structure has the follow- 
ing form: 


typedef struct _VIOCURSORINFO { 


USHORT yStart; 
USHORT cEnd; 
USHORT cx; 
USHORT attr; 

} VIOCURSORINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been créated previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_INVALID_HANDLE 
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Example This example calls VioGetCurType to retrieve the current cursor type, changes 
: the attribute to hidden or visible (the opposite of what it was), and calls 
VioSetCurType to set the new cursor type: 
VIOCURSORINFO viociCursor; 


VioGetCurType (&viociCursor, 0); /* retrieves current cursor type */ 
viociCursor.attr = * flips attribute to hidden/visible */ 


(viociCursor.attr == -1) ? O: -1; 
VioSetCurType (&viociCursor, 0); /* sets new cursor type «/ 
See Also VioGetCurPos, VioSetCurType 


—@ VioGetDeviceCellSize 
USHORT VioGetDeviceCeliSize (pcRows, pcColumns, hvps) 


PSHORT pcRows; /« pointer to variable for cell height «/ 
PSHORT pcColumns; /s pointer to variable for cell width »/ 
HVPS hvps; /» presentation-space handle »/ 


The VioGetDeviceCellSize function retrieves the size of the current device cell. 


Parameters pcRows Points to the variable that specifies the height (in pels) of the device 
. . cell. 


pcColumns Points to the variable that specifies the width (in pels) of the 
device cell. . 


hvps Identifies the advanced video-input-and-output (A VIO) presentation 
space. This presentation space must have been created previously by using the 
VioCreatePS function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 
See Also VioCreatePS, VioSetDeviceCellSize 


— VioGetFont 


USHORT VioGetFont( pviofi, hvio) 
PVIOFONTINFO pviofi; /« pointer to structure for font information «/ 
HVIO hvio; _? /« video handle »/ 


The VioGetFont function retrieves a specified font. A font consists of one bit- 
map for each character in a character set. The bitmaps define the character 
shapes. The VioGetFont function retrieves a copy of either the current font or a 
font from the ROM of the video display adapter. 


Parameters pviofi Points to the VIOFONTINFO structure that specifies the request type 
, and receives the font information. The VIOFONTINFO structure has the follow- 
ing form: :.. . . 
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Return Value 


Comments 


Example 


See Also 


VioGetMode 


typedef struct  VIOFONTINEFO { 
USHORT cb; 
USHORT type; 


m 
USHORT cxCell; 


USHORT cyCell; 

PVOID pbData; 

USHORT cbData; 
} VIOFONTINEFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_FONT 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_ROW 


Although the VioGetFont function can retrieve fonts for many display adapt- 
ers, the fonts for some adapters are not available. In most cases, the function 
retrieves a full 256-character font. This font may consist of a complete ROM 
font, or it may be derived from downloaded fonts that are saved in the adapter’s 
BIOS. The current font is defined by the most recent DosSetCp or VioSetCp 
function, or it can be set by using the VioSetFont function. 


This example calls the VioGetFont function to obtain the current font. When it 
returns, the exCell and cyCell fields will contain the dimensions (in points) of a 
character cell. The pbData field points to the font: 


VIOFONTINEFO viofiFont; 


viofiFont.cb = sizeof (viofiFont) ; 7* length of structure */ 
viofiFont.type = VGFI_GETCURFONT; /* retrieves current font */ 
viofiFont.cxCell = 0; /* clears columns * 
viofiFont.cyCell = 0; /* clears rows */ 
viofiFont.pbData = OL; /* address of data area */ 
viofiFont.cbData = 7* length of data area * 


O; 
VioGetFont (&viofiFont, 0); 


DosSetCp, VioSetCp, VioSetFont 


USHORT VioGetMode( pviomi, hvio) 
PVIOMODEINFO pviomi; /« pointer to structure for screen mode information »/ 


HVIO hvio; 


/x video handle x/ 


The VioGetMode function retrieves the current screen mode. The screen mode 
defines the display mode (text or graphics), the number of colors being used (2, 
4, or 16), and the width and height of the screen in both character cells and 
pels. 


The VioGetMode function is a family API function. 
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Parameters pviomi_ Points to the VIOMODEINFO structure that receives the screen-mode 
information. The VIOMODEINFO structure has the following form: 


typedef struct _VIOMODEINFO { 
USHORT cb; 
UCHAR fbType; 
UCHAR' color; 
USHORT col; 
USHORT row; 
USHORT hres; 
USHORT vres; 
} VIOMODEINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_LINVALID_LENGTH 


Example This example calls VioGetMode to retrieve the mode information for the screen: 
VIOMODEINFO viomi; 
viomi.cbh = sizeof (viomi); 
VioGetMode(&viomi, 0); 
if (viomi.fbType == 0) 
VioWrtTTY ("Monochrome display\n\r", 20, 0); 
See Also VioGetState, VioSetMode 
VioGetOrg 
USHORT VioGetOrg(psRow, psCo/umn, hvps) 
PSHORT psRow; /« pointer to variable for row number »/ 
PSHORT psColumn; /« pointer to variable for column number «/ 
HVPS hvps; /» presentation-space handie »/ 


The VioGetOrg function retrieves the origin of an advanced video-input-and- 
output (AVIO) presentation space. 


Parameters psRow Points to the variable that receives the row number of the cell cur- 
rently mapped to the upper-left corner of the window. 


psColumn Points to the variable that receives the column number of the cell 
currently mapped to the upper-left corner of the window. 


hvps_ Identifies the AVIO presentation space. This presentation space must 
have been created previously by using the VioCreatePS function 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 


See Also VioCreatePS, VioSetOrg . 
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m@ VioGetPhysBuf 


USHORT VioGetPhysBuf (pviopb, usReserved) 
PVIOPHYSBUF pviopb; /« pointer to structure for physical video buffer »/ 
USHORT usReserved; /x must be zero »/ 


Parameters 


Return Value 


Comments 


Example 


See Also 


The VioGetPhysBuf function retrieves the selector of the physical video buffer. 
The physical video buffer contains the text or graphics information that defines 
the current screen image. In text mode, the buffer contains the character and 
attribute for each character cell. In graphics mode, the buffer is a bitmap (in one 
or more planes) of the image on the screen. The content of the screen depends 
on the current screen mode and the type of display adapter. 


The VioGetPhysBuf function is a family API function. 


pviopb Points to the VIOPHYSBUF structure that specifies the address and 
length of the physical video buffer, and receives the selector(s) used to address 
the video buffer. The VIOPHYSBUF structure has the following form: 


typedef struct _VIOPHYSBUF { 
PBYTE pBuf; 
ULONG cb; 
SEL asel{l]; 

} VIOPHYSBUE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
usReserved Specifies a reserved value. This parameter must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_IN_BG 
ERROR_VIO_LINVALID_HANDLE 


Since the physical video buffer is subject to change by the current foreground 
process, only the foreground process should access the buffer. To ensure that 
the foreground process has complete control of the physical buffer, use the 
VioScrLock function. 


This example locks the screen, calls VioGetPhysBuf to retrieve the address of 
the physical video buffer, unlocks the screen, and assigns the address of the 
physical video buffer to a pointer: 


VIOPHYSBUF viopbBuffer; 

PCH pchScreen; 

USHORT fStatus; 

viopbBuf.pBuf = OxB8OO0L; 

viopbBuf.cbh = 4000; 
VioScrLock(LOCKIO_WAIT, &fStatus, 0); 
VioGetPhysBuf (&viopbBuf, 0); 
VioScrUnLock (0) ; 

pchScreen = MAKEP(viopbBuf.asel[0]), 0); 


VioGetBuf, VioScrLock, VioScrUnLock, VioShowBuf 


@ VioGetState 
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USHORT VioGetState ( pvoidState, hvio) 


PVOID pvoidState; 


HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/x pointer to structure for state information »«/ 
/» video handle »/ 


The VioGetState function retrieves the current settings of the palette registers, 
the overscan (border) color, or the blink/background intensity switch. 


pvoidState Points to the structure that receives the state information. The 
structure type, which depends on the request type specified in 

the type field of each structure, is one of the following: VIOPALSTATE, 
VIOOVERSCAN, or VIOINTENSITY. These structures have the following 
forms: 


typedef struct _VIOPALSTATE { 
USHORT cb; . 
USHORT type; 
USHORT iFirst; 
USHORT acolor([1]; 
} VIOPALSTATE ; 


typedef struct _VIOOVERSCAN { 
USHORT cb; 
USHORT type; 
USHORT color; 

} VIOOVERSCAN; 


typedef struct _VIOINTENSITY { 
USHORT cb; 
USHORT type; 
USHORT fs; 

} VIOINTENSITY; 


For each structure, you must set the cb and type fields before calling the func- 
tion. Not all values for the type field are valid for all screen modes. 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_LINVALID_LENGTH 


This example calls the VioGetState function to retrieve the settings for each of 
the 16 palette registers: 
BYTE abState [38]; 


PVIOPALSTATE pviopal; 
pviopal = (PVIOPALSTATE) abState; 


pviopal->cb = sizeof (abState) ; /* structure size */ 
pviopal->type = 0; /* retrieves palette registers 7 
pviopal->iFirst = 0; /* first palette register to return */ 


VioGetState(pviopal, 0); 


VioGetMode, VioSetState 
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M VioModeUndo 


USHORT VioModeUndo ( fRelinquish, fferminate, hvio) 


USHORT fRelinquish; 
USHORT fTerminate; 
USHORT hvio; 


Parameters 


Return Value 


See Also 


—H VioModeWait 


/x ownership flag «/ 
/« termination flag «/ 
/x video handle — «/ 


The VioModeUndo function cancels a request by a process to be notified of a 
change in video mode. A process makes this request by calling the VioMode- 
Wait function. The request forces the calling thread to wait until the video mode 
changes. The VioModeUndo function cancels the request and permits the thread 
to continue (or ends the thread, if requested to do so). 


MS OS/2 permits only one process in a screen group to request notification of 
a video-mode change. The first process to make a request owns it. Thereafter, 
other processes must wait for the owning process to relinquish the request 
before being granted ownership. To force a process to relinquish ownership of 
the request, use the VioModeUndo function. 


Only the process that owns the change-mode request may call the VioModeUndo 
function. . 


fRelinquish Specifies whether the process should retain or relinquish owner- 
ship of the request. If this parameter is UNDOILGETOWNER, the process 
retains ownership and can make the request again without competing with other 
processes. If this parameter is UNDOILRELEASEOWNER, the process relin- 
quishes ownership of the request and is canceled by VioModeUndo. 


fTerminate Specifies whether to terminate the thread waiting for the mode 
change. If this parameter is UNDOK_ERRORCODE, the thread continues and 
receives an error value from the VioModeWait function. If the parameter is 
UNDOK_TERMINATE, the thread terminates. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_FUNCTION_OWNED 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_NO_MODE_THREAD 


VioModeWait 


USHORT VioModeWait( fEvent, pfNotify, hvio) 


USHORT fEvent; 
PUSHORT pfNotify; 
USHORT hvio; 


/» event flag +/ 
/« pointer to variable for notify flag +/ 
/« video handle »/ 


The VioModeWait function waits for a change in the current video mode before 
returning. When a change occurs, MS OS/2 sets the variable pointed to by the 


Parameters 


Return Value 


Comments 


See Also 
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pfNotify parameter to a value indicating the type of change. The thread may then 
restore the video registers or carry out other tasks related to restoring the video 
mode for the process. 


The VioModeWait function is used typically by graphics programs (or text pro- 
grams that access video registers directly) to restore the screen after a pop-up 
screen has closed. Pop-up screens often change the video mode and video-reg- 
ister values without fully restoring them when closed. A thread that calls the 
VioModeWait function waits until a pop-up screen closes so that it can restore 
the screen. 


MS OS/2 permits only one process in a screen group to wait for a video-mode 
change. The first process to make a request owns it. 


fEvent Specifies the event flag of the event to wait for. If this parameter is 
VMWR_POPUP, the function waits for a pop-up screen to close. No other flags 
are permitted. 


pfNotify Points to the variable that receives a flag specifying the action to 
carry out in response to the given event. If this flag is VMWN_POPUP, the pro- 
cess should restore the video mode. No other values are returned. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_FUNCTION_OWNED 
ERROR_VIO_LINVALID_PARMS 
ERROR_VIO_RETURN 


A program should use the VioModeWait function if it changes the video regis- 
ters directly. MS OS/2 automatically saves and restores the physical video buffer 
and screen mode whenever a pop-up screen is used. 


The thread that calls VioModeWait should carry out only those tasks directly 
related to restoring the screen mode. Whenever a mode change occurs, the 
thread should restore the mode and call VioModeWait as quickly as possible. 
The thread should not call MS OS/2 functions (netiher directly nor indirectly 
through other functions) that may generate pop-up screens or error pop-up 
screens. Doing so may cause MS OS/2 to lock up (that is, each call of the 
thread generates a pop-up screen, which in turn calls the thread and generates 
another pop-up screen, and so on). You can use the VioModeUndo function to 
end the thread when it is no longer needed. 


Programs that save and restore the video mode and screen before and after a 
screen switch should use the VioSaveRedrawWait function. 


VioModeUndo, VioPopUp, VioSaveRedrawWait 
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HM VioPopUp 


USHORT VioPopUp( pfWait, hvio) 


PUSHORT p/fWait; 
HVIO hvio; 


Parameters 


/« pointer to variable for wait/no-wait flag +/ 
/« video handle «/ 


The VioPopUp function opens a pop-up screen. A pop-up screen is a temporary 
text-mode screen that a process can use to display error and warning messages 
without altering the content of the foreground screen. Pop-up screens are used 
typically by background processes to display messages when the screen is not 
available. 


The pop-up screen can be opaque or transparent, as specified by the flag pointed 
to by the pfWait parameter. If the pop-up screen is opaque, the function changes 
the screen mode (if the mode is not already set for 25 lines by 80 columns of 
text) and clears the screen, moving the cursor to the upper-left corner. If the 
pop-up screen is transparent, the function uses the current screen mode and 
leaves the screen and the cursor unchanged. _ 


Once the pop-up screen is open, the process may call any of the following Vio 
functions: 


VioEndPopUp . VioReadCellStr VioSetFont 


VioGetAnsi VioReadCharStr_ _VioSetState 
VioGetCp VioScrollIDn VioWrtCellStr 
VioGetConfig VioScrollLf VioWrtCharStr 
VioGetCurPos VioScrollRt VioWrtCharStrAtt 
VioGetCurType _-VioScrollUp VioWrtNAttr 
VioGetFont VioSetCp VioWrtNCell 
VioGetMode VioSetCurPos VioWrtNChar 
VioGetState VioSetCurType §VioWrtTTY 


The process opening the pop-up screen receives all subsequent keyboard input, 
and MS OS/2 disables the keys that it normally uses switch from one screen 
group to another. While the pop-up screen is open, the process must not access 
or modify the physical video buffer. Also, it must not call the DosExecPgm 
function. 


Only one pop-up screen may be open at any given time. If a process attempts to 
open one pop-up screen while another is already open, the VioPopUp function 
waits until the previous screen is closed before opening the new one. 


pfWait Points to the variable that specifies whether the pop-up screen is to 
be opaque or transparent, and whether the function should wait for any open 
pop-up screen to close. It can be any combination of either VP_NOWAIT or 
VP_WAIT and either VP_LOPAQUE or VP _TRANSPARENT. These flags are 
defined as follows: 


Value Meaning 

VP_NOWAIT Return immediately if a pop-up screen alresiy 
exists. 

VP_WAIT Wait if a pop-up screen already exists. The func- 


tion opens a new pop-up screen as soon as the 
existing one is closed. 


Return Value 


Comments 


Example 


See Also 
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Value Meaning 
VP_OPAQUE Set the screen mode for 25 lines by 80 columns of 


text, clear the screen, and move the cursor to the 
upper-left corner. 


VP_TRANSPARENT Create a transparent pop-up screen. The function 
does not change the screen mode, clear the 
screen, or move the cursor. To create a trans- 
parent pop-up screen, the screen must be in text 
mode already. 


hvio Identifies a reserved value. This parameter must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_EXISTING_POPUP 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_NO_POPUP 


Before opening a pop-up screen, MS OS/2 saves the physical video buffer of the 
existing screen. While the pop-up screen is open, MS OS/2 blocks any Vio func- 
tions called by the process that owns the previous screen. If this process gen- © 
erates any output, MS OS/2 displays the output after the pop-up screen closes. 


You can close a pop-up screen by using the VioEndPopUp function. VioEnd- 
PopUp restores the screen mode and the screen buffer; it also restores keyboard 
input to the previous process and enables the key combination MS OS/2 uses to 
switch screen groups. In some cases, the VioEndPopUp function may not com- 
pletely restore the screen. For these cases, use the VioModeWait function to 
restore the screen. 


You cannot use transparent pop-up screens if the foreground process has called 
the VioSavRedrawWait function. 


If a process registers a replacement VioPopUp function (by calling the Vio- 
Register function), MS OS/2 uses the replacement function only if the fore- 
ground process requests a pop-up screen. If a background process requests. 
a pop-up screen, MS OS/2 uses the default VioPopUp function. 


This example calls the VioPopUp function to create a pop-up screen, and waits 
for the pop-up screen if another pop-up screen is already active: 


USHORT fWait = VP_WAIT | VP_OPAQUE; 
VioPopUp (&fWait, 0); 


- /* message and user interaction would go here */ 


VioEndPopUp (0) ; /* ends pop-up screen */ 


DosExecPgm, VioEndPopUp, VioGetPhysBuf, VioModeWait, VioRegister, 
VioSavRedrawWait 
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M VioPrtSc 


USHORT VioPrtSce(hvio) 
HVIO hvio; —/s video handle +/ 


Parameters 


Return Value 


See Also 


VioPrtScToggle 


. The VioPrtSc function copies the contents of the screen to the printer. 


This function is reserved for system use. It is called whenever the PRINTSCREEN 
key is pressed. A process can, however, replace VioPrtSe with a custom screen- 
printing function by using the VioRegister function. If a process does replace 
the VioPrtSce function, all other processes in the screen group will also use the 
replacement function. This gives a peek the capability of capturing input from 
the PRINTSCREEN key. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_SMG_ONLY 


VioPrtScToggle, VioRegister 


USHORT VioPrtScToggle (hvio) 
HVIO hvio; /« video handle «/ 


Parameters 


Return Value 


See Also 


The VioPrtScToggle function enables or disables the printer echo feature. 


This function is reserved for system use. It is called whenever the CTRL+PRTSC 
key combination is pressed. The first press enables the printer echo feature, the 
second disables it. A process can replace VioPrtScToggle, however, with a cus- 
tom function by using the VioRegister function. If a process does replace the 
VioPrtScToggle function, all processes in the screen group will also use the 
replacement function. This gives a process the capability of capturing input from 
the CTRL+PRTSC key combination. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_SMG_ONLY 


VioPrtSc, VioRegister 
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M@ VioQueryFonts 
USHORT VioQueryFonts(pcbMetrics, pfm, cbMetrics, pcFonts, pszFacename, flOptions, hvps) 


PLONG pcbMetrics; /« pointer to variable for structure length »/ 
PFONTMETRICS pfm; /» pointer to structure for font metrics —«/ 
LONG cbMetrics; /« length of structure »/ 
PLONG pcFonts; /« pointer to variable for number of fonts «/ 
PSZ pszFacename; /« pointer to string for face name »/ 
ULONG flOptions; /« enumeration options »/ 
HVPS hvps; /» presentation-space handle »/ 


The VioQueryFonts function retrieves a font-metrics structure (or structures) 
that contains characteristics of the fonts that match the specified face name. 
These characteristics, or font metrics, are returned for as many matching fonts 
as will fit in the structure pointed to by the pfm parameter. 


After examining the returned data, the application selects the font most appro- 
priate for its requirements, and if necessary, forces selection of a particular 
font by specifying the IMatch field (as returned in the pfm parameter) in the 
FATTRS structure for the VioCreateLogFont function. 


By specifying zero for the pcFonts parameter and then examining the value 
returned, the application determines how many fonts match the specified face 
name. 


All sizes are returned in world coordinates. For more information, see the 
Microsoft Operating System/2 Programmer’s Reference, Volume 1. 


Parameters pcbMetrics Points to the variable that receives the length (in bytes) of each 
FONTMETRICS structure. The structure pointed to by the pfm parameter must 
contain the number of bytes given by pcFonts x pcMetrics. 


pfm Points to the FONTMETRICS structure that receives the font metrics of 
the specified matching fonts. The format for each record is as defined in the 
GpiQueryFontMetrics function. The FONTMETRICS structure has the following 
form: 


typedef struct _FONTMETRICS { 
CHAR szFamilyname [FACESIZE]; 
CHAR szFacename [FACESIZE]; 
USHORT idRegistry; 
USHORT usCodePage; 


LONG 1EmHeight; 

LONG 1XHeight; 

LONG 1MaxAscender; 
LONG 1l1MaxDescender; 
LONG lLowerCaseAscent; 
LONG lLowerCaseDescent; 
LONG linternalLeading; 
LONG l1ExternalLeading; 
LONG lAveCharWidth; 
LONG 1MaxChariInc; 

LONG 1EmInc; 

LONG 1MaxBaselineExt; 


SHORT sCharS lope; 
SHORT sInlineDir; 
SHORT sCharRot; 
USHORT usWeightClass; 
USHORT usWidthClass; 
SHORT sXDeviceRes; 
SHORT sYDeviceRes; 
SHORT sFirstChar; 
SHORT sLastChar; 
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Return Value 


See Also 


VioQuerySetlds 


SHORT sDefaultChar; 
SHORT sBreakChar; 

SHORT sNominalPointSize; 
SHORT sMinimumPointSize; 
SHORT sMaximumPointSize; 
USHORT fsType; 

USHORT fsDefn; 

USHORT fsSelection; 
USHORT fsCapabilities; 


LONG 1SubscriptXSize; 
LONG 1SubscriptyYSize; 
LONG 1SubscriptxoOffset; 
LONG £18ubscriptYOffset; 
LONG 1SuperscriptXSize; 
LONG lSuperscriptYSize; 
LONG l1SuperscriptXOffset; 
LONG 1SuperscriptYOffset; 
LONG lUnderscoreSize; 
LONG lUnderscorePosition; 
LONG 1StrikeoutSize; 
LONG 1StrikeoutPosition; 


SHORT sKerningPairs; 
SHORT sReserved; 
LONG 1Match; 

} FONTMETRICS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
cbMetrics Specifies the length (in bytes) of the font-metrics structure(s). 


pcFonts Points to the variable that receives the number of fonts for which the 
application requires metrics. 


pszFacename Points to the null-terminated string that specifies the face name. 


flOptions Specifies whether to enumerate public or private fonts. This param- 
eter may be any combination of the following values: 


Value Meaning 
VOF_PUBLIC Enumerate public fonts. 
VQF_PRIVATE Enumerate private fonts. 


hvps_ Identifies the advanced video-input-and-output (A VIO) presentation 
space. This handle must have been created previously by using the VioCreatePS 
function. 


The return value is the number of fonts not retrieved. The return value is - 1 if 
an error occurs. 


GpiQueryFonts, VioCreateLogFont, VioCreatePS 


USHORT VioQuerySetlds( pa/cids, pachNames, palTypes, cSets, hvps) 


PLONG pailcids; 
PSTR8 pachNames; 
PLONG pal/Types; 
LONG cSets; 

HVPS hvps; 


/« pointer to array for local identifiers for fonts «/ 


/« pointer to array for font names »/ 
/« pointer to array for object types x/ 
/« number of local identifiers in use x/ 
/« presentation-space handle x/ 


The VioQuerySetIds function retrieves information about all available logical 
fonts. This function is similar to the GpiQuerySetIds function. 


Parameters 


Return Value 
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palcids Points to the array that receives the local identifiers for the fonts. 


pachNames Points to the array that receives the 8-character names for the 
fonts. 


palTypes Points to the array that receives the object types for the fonts. All 
fonts have the object type LCIDT_FONT. 


cSets Specifies the number of local identifiers currently in use and therefore 
the maximum number of objects for which information can be returned. You 
can determine this value by using the GpiQueryNumberSetlIds function. 


hvps_ Identifies the advanced video-input-and-output (A VIO) presentation 
space. This handle must have been created previously by using the VioCreatePS 
function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


See Also GpiQueryNumberSetlds, GpiQuerySetlds, VioCreatePS 

VioReadCellStr 

USHORT VioReadCellStr( pchCellString, pcb, usRow, usColumn, hvio) 

PCH pchCellString; /« pointer to buffer for string »/ 

PUSHORT pcb; /» pointer to variable for string length «/ 

USHORT usRow; /« starting location (row) »/ 

USHORT usColumn; /« starting location (column) »/ 

HVIO hvio; /« video handle »/ 
The VioReadCellStr function reads one or more cells (character-attribute pairs) 
from the screen, starting at the specified location. If the string is longer than the 
current line, the function continues reading it at the beginning of the next line 
but does not read past the end of the screen. 
The VioReadCellStr function is a family API function. 

Parameters pchCellString Points to the buffer that receives the cell string. 


Return Value 


pcb Points to the variable that specifies the length (in bytes) of the buffer. The 
length should be an even number. On return, this function copies the length of 
the string to the variable. 


usRow Specifies the starting row of the cell string to read. 
usColumn Specifies the starting column of the cell string to read. 
hvio Identifies an advanced video-input-and-output (A VIO) presentation 


‘space. For AVIO programs, this handle must have been created previously using 


the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 
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Example This example calls VioReadCellStr to read Line 0, then calls the VioWrtCellStr 
function to write the cell string to Line 24: 
CHAR achCells [160]; 
USHORT cb = sizeof (achCells) ; 
VioReadCellStr (achCells, /* buffer for string * 
&eb, * pointer to variable for string length */ 
oO, * starting location (row) a/ 
O, /* starting location (column) */ 
O); * video handle */ 
VioWrtCellStr(achCells, cb, 24, 0, O); 
See Also VioReadCharStr, VioWrtCellStr 
VioReadCharStr 
USHORT VioReadCharStr(pchString, pcb, usRow, usColumn, hvio) 
PCH pchString; /« pointer to buffer for string »/ 
PUSHORT pcb; /« pointer to variable for lengtl of buffer «/ 
USHORT usRow; /« starting location (row) »/ 
USHORT usColumn; /« starting location (column) »/ 
HVIO hvio: /» video handle »/ 
The VioReadCharStr function reads a character string from the screen, starting 
at a specified location. If the character string is longer than the current line, the 
function continues reading it at the beginning of the next line but does not read 
past the end of the screen. 
The VioReadCharStr function is a family API function. 
Parameters pchString Points to the buffer that receives the character string. 


Return Value 


pcb Points to the variable that specifies the length (in bytes) of the buffer. On 
return, the function copies the length of the string to the variable. 


usRow Specifies the starting row of the character to be read. 
usColumn Specifies the starting column of the character to be read. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


Example 


See Also 


VioRegister 
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This example calls VioReadCharStr to read a character string that is 80 charac- 
ters long, starting at Row 1, Column 0 of the screen. It then calls the VioWrt- 
CharStr function to write the character string to Row 24, Column 0. 


CHAR achString[80]; 
USHORT cb = sizeof (achString) ; 


VioReadCharStr (achString, /* string buffer * 
&ob, /* length of buffer */ 
1, /* row a/ 
oO, /* column */ 
* video handle a/ 


O); 
VioWrtCharStr (achString, cb, 24, 0, O); 


VioReadCellStr, VioWrtCharStr 


USHORT VioRegister( pszModuleName, pszEntryName, flFunction1, flFunction2) 
PSZ pszModuleName; /x pointer to module name x/ 


PSZ pszEntryName; 


ULONG flFunction?; 
ULONG flFunction2; 


Parameters 


/« pointer to entry-point name «/ 
/« function flag 1 »/ 
/« function flag 2 »/ 


The VioRegister function registers a Vio subsystem within a screen group. 
VioRegister temporarily replaces one or more default Vio functions, as specified 
by the flFunction1 and flFunction2 parameters, with the functions pointed to by 
the pszModuleName parameter. Once VioRegister replaces a function, MS OS/2 
passes any subsequent call to the replaced function to a function in the given 
module. If you do not replace a function, MS OS/2 continues to call the default 
Vio function. | 


pszModuleName Points to the null-terminated string that specifies the name 
of the dynamic-link module containing the replacement Vio functions. The string 
must be a valid filename. 


pszEntryName _ Points to the nulierainated string that specifies the dynamic- 
link entry-point name of the function that replaces the specified Vio functions. 
For a full description, see the following “Comments” section. © 


fiFunction1 Specifies the Vio function(s) to replace. This parameter can be 
any combination of the following values: 


Value Meaning 
VR_VIOGETCURPOS Replace VioGetCurPos. 
VR_VIOGETCURTYPE Replace VioGetCurType. 
VR_VIOGETMODE Replace VioGetMode. 
VR_VIOGETBUF Replace VioGetBuf. 
VR_VIOGETPHYSBUF ' Replace VioGetPhysBuf. 
VR_VIOSETCURPOS Replace VioSetCurPos. 
VR_VIOSETCURTYPE Replace VioSetCurType. 
VR_VIOSETMODE Replace VioSetMode. 


VR_VIOSHOWBUF Replace VioShowBuf. 
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Value 


Yr wrTm TA YN SNTY A 


VR_VIOREADCHARSTR 
VR_VIOREADCELLSTR 
VR_VIOWRTNCHAR 
VR_VIOWRTNATTR 
VR_VIOWRTNCELL 
VR_VIOWRTITY 
VR_VIOWRTCHARSTR 
VR_VIOWRTCHARSTRATT 
VR_VIOWRTCELLSTR 
VR_VIOSCROLLUP 
VR_VIOSCROLLDN 
VR_VIOSCROLLLF 
VR_VIOSCROLLRT 
VR_VIOSETANSI 
VR_VIOGETANSI 
VR_VIOPRTSC 
VR_VIOSCRLOCK 
VR_VIOSCRUNLOCK 
VR_VIOSAVREDRAWWAIT 
VR_VIOSAVREDRAWUNDO 
VR_VIOPOPUP 
VR_VIOENDPOPUP 
VR_VIOPRTSCTOGGLE 


Meaning 

Repiace VioReadCharStr. 
Replace VioReadCellStr. 
Replace Vio WrtNChar. 
Replace Vio WrtNAttr. 
Replace VioWrtNCell. 
Replace Vio WrtTTY. 
Replace VioWrtCharStr. 
Replace Vio WrtCharStrAtt. 
Replace Vio WrtCellStr. 
Replace VioScrollUp. 
Replace VioScrollDn. 
Replace VioScrollLf. 
Replace VioScrollRt. 
Replace VioSetAnsi. 
Replace VioGetAnsi. 
Replace VioPrtSc. 

Replace VioSerLock. 
Replace VioScrUnLock. 
Replace VioSavRedrawWait. 
Replace VioSavyRedrawUndo. 
Replace VioPopUp. 
Replace VioEndPopUp. 
Replace VioPrtScToggle. 


fiFunction2 Specifies the Vio function(s) to replace. This parameter can be 
any combination of the following vales 


- Value 


VR_VIOMODEWAIT 
VR_VIOMODEUNDO 
VR_VIOGETFONT 
VR_VIOGETCONFIG 
VR_VIOSETCP 
VR_VIOGETCP 
VR_VIOSETFONT 
VR_VIOGETSTATE 
VR_VIOSETSTATE 


Replace VioMode Wait. 
Replace VioModeUndo. 
Replace VioGetFont. 
Replace VioGetConfig. 
Replace VioSetCp. 
Replace VioGetCp. 
Replace VioSetF ont. 
Replace VioGetState. 
Replace Vio SetState. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_INVALID_ASCIZ 
ERROR_VIO_INVALID_MASK 
ERROR_VIO_REGISTER 


Comments MS OS/2 passes a Vio function to the given module by preparing the stack and 
calling the function pointed to by the pszEntryName parameter. The specified 
module must export the entry-point function name. The entry-point function 
must determine which function is being requested (by checking the function code 
on the stack), then pass control to the appropriate function in the module. The 
entry-point function may then access any additional parameters placed on the 
stack by the original call. 


Only one process in a screen group may use the VioRegister function at any 
given time. That is, only one process at a time can replace Vio functions. The 
process can restore the default Vio functions by calling the VioDeRegister func- 
tion. A process can replace Vio functions any number of times, but only by first 
restoring the default functions and then reregistering the new functions. 


The entry-point function (FuncName) must have the following form: 


SHORT FAR FuncName(selDataSeg, usReserved1, fFunction, ulReserved2, 
usParam1, usParam2, usParam3, usParam4, usParam5, usParam6) 


SEL selDataSeg; 
USHORT usReserved1; 
USHORT fFunction; 
ULONG ulReserved2; 
USHORT usParam1;. 
USHORT usParam2; 
USHORT usParam3; 
USHORT usParam4; 
USHORT usParam5; 
USHORT usParam6; 
Parameter Description 
selDataSeg Specifies the data segment selector of the process call- 
ing the Vio function. 
usReserved1 Specifies a reserved value that must not be changed. 
This value represents a return address for the MS OS/2 
function that routes calls to Vio functions. 
{Function Specifies the function code of the function request. 
This parameter can be one of the following values: 
Value Meaning 
0x0000 VioGetPhysBuf called. 
0x0001 VioGetBuf called. 
0x0002 VioShowBuf called. 


0x0003 VioGetCurPos called. 
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Value 
0x0004 
0x0005 
0x0006 
00007 
0x0008 
0x0009 
0x000A 
0x000B 
0x000C 
0x000D 
0x000E 
0x000F 
0x0010 
0x0011 
0x0012 
0x0013 
0x0014 
0x0015 
0x0016 
0x0017 
0x0018 
0x0019 
Ox001A 
0x001B 
0x001C 
0x001D 
0x001B 
0x001F 
0x0020 
0x0021 
0x0022 
0x0023 
0x0024 
0x0025 
0x0026 
0x0027 
0x0028 


VioGetMode called. 
VioSetCurPos called. 
VioSetCurType called. 
VioSetMode called. 
VioReadCharStr called. 
VioReadCellStr called. 
Vio WrtNChar called. 
VioWrtNAttr called. 
Vio WrtNCell called. 
Vio WrtCharStr called. 
VioWrtCharStrAtt called. 
Vio WrtCellStr called. 
VioWrtTTY called. 
VioScrollUp called. 
VioScrollDn called. 
VioScrollLf called. 
VioScrollRt called. 
VioSetAnsi called. 
VioGetAnsi called. 
VioPrtSe called. 
VioScrLock called. 
VioScrUnLock called. 
VioSavRedrawWait called. 
VioSavRedrawUndo called. 
VioPopUp called. 
VioEndPopUp called. 
VioPrtScToggle called. 
VioModeWait called. 
VioModeUndo called. 
VioGetFont called. 
VioGetConfig called. 
VioSetCp called. 
VioGetCp called. 
VioSetFont called. 
VioGetState called. 


VioSetState called. 


See Also 
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Parameter Description 


ulReserved2 Specifies a reserved value that must not be changed. 
This value represents the return address of the program 
that calls the specified Vio function. 


usParam1-usParam6 Specifies up to six values passed with the original call to 
the Vio function. Not all requests include all six param- 
eters since not all Vio functions use six parameters. 
The number and type of parameters used depend on 
the specific function. 


The entry-point function should determine which function is requested and then 
carry out an appropriate action by using the passed parameters. The entry-point 
function can call a function within the same module to carry out the task. The 
entry-point or replacement function must leave the stack in the same state as it 
was received. This is required since the return addresses on the stack must be 
available in the correct order to return control to the program that originally 
called the VioRegister function. 


The registered function should return - 1 if it wants the original function called, 
0 if no error occurred, or an error value. 


In general, if the function needs to access the display, it must use the input-and- 
output control functions for the display. For more information, see Chapter 3, 
“Input-and-Output Control Functions.” 


The VioRegister function itself cannot be replaced. 


If a process replaces the VioPopUp function, only the foreground process has 
access to the replacement function. Background processes continue to call the 
default VioPopUp function. 


VioDeRegister, VioPopUp, VioSetCurPos 


H VioSavRedrawUndo 


USHORT VioSavRedrawUndo ( fRelinquish, fferminate, hvio) 


USHORT fRelinquish; 
USHORT fTerminate; 
HVIO hvio; 


/« retain/relinquish ownership flag «/ 
/« terminate/continue flag s/ 
/« video handle a/ 


The VioSavRedrawUndo function cancels a request by a process to be notified 
when MS OS/2 switches screen groups. A process requests to be notified by 
calling the VioSavRedrawWait function. The request forces the calling thread to 
wait until a screen switch occurs. VioSavRedrawUndo cancels the request and 
allows the thread to continue (or terminates the thread, if requested to do so). 


MS OS/2 permits only one process in a screen group to request screen switch 
notification. The first process to make a request owns it. Thereafter, other pro- 
cesses must wait for the owning process to relinquish the request before being 
given ownership. To force the process to relinquish ownership of the request, 
use the VioSavRedrawUndo function. 


Only the process that owns the change-mode request can call the VioSav- 
RedrawUndo function. 
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Parameters 


Return Value 


See Also 


fRelinquish Specifies whether a process should retain or relinquish owner- 


_ ship of the request. If this parameter is UNDOILGETOWNER, the process 


relinquishes ownership and is canceled by this function. If the parameter is 
UNDOIRELEASEOWNER, the process retains ownership and can repeat the 
request without competing with other processes. 


fTerminate Specifies whether to terminate the thread waiting for the mode 
change. If this parameter is UNDOK_ERRORCODE, the thread continues and 
receives an error value from the VioSavRedrawWait function. If the parameter 
is UNDOK_TERMINATE, the thread terminates. 


hvio_ Identifies an advanced video-input-and-output (A VIO) presentation 


' space. For AVIO programs, this handle must have been created previously using 


the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_FUNCTION_OWNED 
ERROR_VIO_LINVALID_PARMS 
ERROR_VIO_NO_SA VE_RESTORE_THD 


VioModeUndo, VioSavRedrawWait 


VioSavRedrawWait 
USHORT VioSavRedrawWait( fEvent, pfNotify, usReserved) 


USHORT fEvent; 
PUSHORT pfNotify; 


/« event flag x/ 
/« pointer to variable for notify flag «/ 


USHORT usReservea; /x must be zero x/ 


Parameters 


The VioSavRedrawWait function waits for a screen switch to occur. When a 
switch occurs, MS OS/2 sets the variable pointed to by the pfNotify parameter to 
a value that indicates the type of changes. The thread may then save or restore 
the display depending on the value pointed to by the pfNotify parameter. The 
thread must also save or restore the complete video mode, the state information, 
the registers, and the contents of the physical video buffer. 


MS OS/2 permits only one process in a screen group to wait for a screen switch. 
The first process to make a request owns it. 


The VioSavRedrawWait function is used typically by graphics programs (or text- 
mode programs that change the video registers directly) to save and restore the 
screen before and after MS OS/2 switches from one screen group to another. 
Screen switching often changes the screen mode and video register values. A 
thread that calls the VioSavRedrawWait function waits until a screen switch 
occurs and is then given control so that it can save or restore the screen. 


fEvent Specifies the event flag of the event to wait for. If this flag is 
VSRWI_SAVEANDREDRAW, the function returns when the screen needs 
to be either saved or restored. If the flag is VSRWILREDRAW,, the function 
returns only when the screen needs to be restored. 


pfNotify Points to the variable that receives the flag specifying the action to 
carry out in response to the given event. If this flag is VSWRN_SAVE, the 


Return Value 


Comments 


See Also 


@ VioScrLock 


VioScrLock 231 


thread saves the video buffer, the registers, and the state information. If the flag 
is VSWRN_REDRAW, the thread restores the video buffer, the registers, and 
the state information. 


usReserved Specifies a reserved value. This parameter must be zero. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_FUNCTION_OWNED 
ERROR_VIO_INVALID_PARMS 
ERROR_VIO_RETURN 


When an application is notified that it should save its screen image, it saves its 
physical video buffer, video mode, and any other information the application 
needs in order to redraw its screen. 


The thread that calls VioSavyRedrawWait should carry out all tasks directly 
related to saving and restoring the screen information. Whenever a screen switch 
occurs, the thread should save or restore the screen and call VioSavRedrawWait 
as quickly as possible. The thread can access the physical video buffer, if neces- 
sary, but since the thread may not be the foreground process, it must not use the 
VioScrLock function to lock the screen. The thread should not call MS OS/2 
functions (neither directly nor indirectly through other functions) that may gen- 
erate pop-up screens or error pop-up screens. Doing so may cause MS OS/2 to 
lock up (that is, each call of the thread generates a pop-up screen, which in turn 
calls the thread and generates another pop-up screen, and so on). You can use 
the VioSavRedrawUndo function to end the thread when it is no longer needed. 


In some cases, a thread may receive a request to restore the screen before 
receiving a request to save the screen. For such requests, the thread must deter- 
mine whether the given request is valid. 


Programs that need to save and restore the screen after a pop-up screen should 
use the VioModeWait function. 


VioGetPhysBuf, VioModeWait, VioSavRedrawUndo 


USHORT VioScrLock ( fWait, pfNotLocked, hvio) 


USHORT fWait; 
PBYTE pfNotLocked; 
HVIO hvio; 


/« wait/no-wait flag »/ 
/« pointer to variable for status »/ 
/« video handle «/ 


The VioSerLock function locks the physical video buffer for a process. While 
the buffer is locked, no other process may lock it. This function is used typically 
to coordinate the output of graphics programs so that only one process writes to 
the physical video buffer at a time. The function indicates when the screen is 
locked by another process and is not available for writing, rather than denying 
processes access to the physical video buffer. 


Only one process in a screen group may lock the screen. If the screen is already 
locked, VioScrLock either waits for the screen to become unlocked or returns 
immediately, as determined by the fWait parameter. Processes that lock the 
screen should unlock it by using the VioScrUnLock function as soon as they 
have completed the output. 
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Parameters 


Return Value 


Restrictions 


Example 


See Also 


VioScroliDn 


If a screen-switch request occurs while the screen lock is in effect, the switch is 
held for at least thirty seconds. If the process does not unlock the screen before 
thirty seconds elapse, MS OS/2 suspends the process and switches the screen. 
The suspended process remains in the background until it is switched back to 
the foreground. 


The VioScrLock function is a family API function. 


fWait Specifies the flag that determines whether the process is to wait until the 
screen input or output can occur. If this flag is LOCKIO_.NOWAIT, the process 
returns immediately if the screen is not available. If the flag is LOCKIO_WAIT, 
the process waits for the screen to become available. 


pfNotLocked Points to the variable that receives the flag specifying whether 
the screen is locked. If this flag is LOCK_SUCCESS, the screen is locked. If 
the flag is LOCK_FAIL, the screen is not locked. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_LOCK 
ERROR_VIO_WAIT_FLAG 


In real mode, the following restriction applies to the VioScrLock function: - 


@ The function always indicates that the lock was successful. 
This example calls VioScrLock and waits until the screen lock can be performed 
(the process is in the foreground): 


USHORT fNotLocked; 
VioScrLock(LOCKIO_WAIT, /* waits until I/O can take place +t*/. 


&f£NotLocked, /* variable to receive lock status */ 
Oo); /* video handle */ 
VioSerUnLock (0) ; 


VioGetPhysBuf, VioScrUnLock 


USHORT VioScrollDn(usTopRow, usLeftCo/, usBotRow, usRightCol, cbLines, pbCell, hvio) 


USHORT usTopRow; 
USHORT usLeftCo/:; 
USHORT usBotRow; 
USHORT usRightCol; 
USHORT cbLines; 
PBYTE pbCell; 

HVIO hvio; 


/» top row »/ 
/» left column s/ 
/x bottom row x/ 
/« right column »/ 


/« number of blank lines «/ 

/« pointer to cell to write «/ 

/» video handle »/ 
The VioScrollDn function scrolls the current screen downward. 
The VioScrollDn function is a family API function. 


Parameters 


Return Value 


Comments 


Example 


See Also 
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usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbLines Specifies the number of lines to be inserted at the top of the screen 
area being scrolled. If this parameter is zero, no lines are scrolled. 


pbCell Points to a character/attribute pair, called a cell, that fills the screen 
area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper- 
left corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollDn function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum 
values. The function clears the screen by using the character/attribute pair 
pointed to by the pbCell parameter. 


This example creates a cell containing the space character (0x20) and a white 
character attribute (0x07 on an EGA color monitor), and calls VioScrollDn to 
clear the screen by using this cell. By changing the character attribute, you could 
change the background color of the screen while clearing it at the same time 
(using vis value OxFFFF for usBotRow, usRightCol, and cbLines clears the 
screen): 


BYTE bCell[2]; 


bCell [0] = 0x20; /* space character */ 

bCell[{1] = Ox07; /* white attribute (EGA) */ 

VioScrol11Dn (0, /* top row 7 
O, /* left column a / 
OxFFEE, /* bottom row */ 
OxFEFE, /* right column */ 
OxFFFE, /* number of lines */ 
bCell, /* cell to write */ 
O); /* video handle */ 


VioScrollLf, VioScroliRt, VioScrollUp 
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a VioScrollLf 


USHORT VioScrollLf(usTopRow, uaLefiCol, UeBotROw: usRightCol, EBCAIIMNE: pbCell, hvio) 


USHORT usTopRow; 
USHORT usLeftCol; 
USHORT usBotRow; 


USHORT usRightCo/; 
USHORT cbColumns; 


PBYTE pbCell; 
HVIO hvio; 


Parameters 


Return Value 


Comments 


Example 


/« top row x/ 
/« left column: »/ 
/x bottom row x/ 
/« right column / 


/»« number of blank columns «/ 
/« pointer to the cell to write «/ 
/« video handle »/ 


The VioScrollLf function scrolls the current screen toward the left. 
The VioScrollLf function is a family API function. 


usTopRow _ Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbColumns Specifies the number of columns of spaces to be inserted at the 
right. If this parameter is zero, no columns are inserted. 


pbCell Points to a character/attribute pair, called a cell, that fills the screen 
area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_ HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper- 

left corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollLf function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their max- 
imum values. The function clears the screen by using the character/attribute pair 
pointed to by the pbCell parameter. 


This example calls VioScrollLf to fill the last ten columns at the right of the 
screen with red hearts on a black background (a value of OxFFFF is used for 
usBotRow and usRightCol): 


See Also 


VioScrollRt 


VioScrolIRt 235 


BYTE bCell[2]; 


bCell[O] = 0x03; /* heart character */ 
bCell[1] = 0x04; /* red attribute (EGA) */ 
VioScrollLf (0, /* top row */ 
O, /* left column a / 
OxFFFF, /* bottom row */ 
OxFFFE, /* right column */ 
10, /* columns */ 
bCell, /* cell to write */ 
O); /* video handle */ 


VioScrolIDn, VioScrollRt, VioScrollUp 


USHORT VioScrollRt (usTopRow, usLeftCol, usBotRow, usRightCol, cbColumns, pbCell, hvio) 


USHORT usTopRow; 
USHORT usLeftCo/; 
USHORT usBotRow; 
USHORT usRightCo/; 
USHORT cbColumns; 
PBYTE pbCell: 

HVIO hvio; 


Parameters 


Return Value 


Comments 


/« top row »/ 
/« left column x/ 
/« bottom row »/ 
/« right column »/ 


/« number of blank columns «/ 
/« pointer to cell to write af 
/x video handle »/ 


The VioScrollRt function scrolls the current screen toward the right. 
The VioScrollRt function is a family API function. 


usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbColumns Specifies the number of columns of spaces to be inserted at the 
left. If this parameter is zero, no columns are inserted. 


pbCell Points to a character/attribute pair, called a cell, that fills the screen 
area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper- 

left corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbColumns, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 
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Example 


See Also 


VioScrollUp 


You can use the VioScrollUp function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbColumns to their max- 


mim 1 tha orran hy tha etarlottedauta nai 
imum values, The function Cicars ine screen vy using tie char acter atiriduwre pair 


pointed to by the pbCell parameter. 


This example calls VioScrollRt to fill the first ten columns at the left of the 
screen with red hearts on a black background (a value of OxFFFF is used for 
usBotRow and usRightCol): 


BYTE bCell[2]; 


bCell1[0] = 0x03; 7* heart character */ 
bCell[1] = 0x04; /* red attribute (EGA) */ 
VioScrollRt (0, /* top row */ 
O, /* left column */ 
OxFFFF, /* bottom row */ 
OxFFFF, 7/* right column */ 
10, /* columns */ 
bCell, /* cell to write */ 
0); /* video handle x/ 


VioScrollDn, VioScrolILf, VioScrollUp 


USHORT VioScroliUp(usTopRow, usLeftCol, usBotRow, usRightCol, cbLines, pbCell hvio) 


USHORT usTopRow; 
USHORT usLeftCol; 
USHORT usBotRow; 
USHORT usRightCol; 
USHORT cbLines; 
PBYTE pbCell; 

HVIO hvio; 


Parameters 


Return Value 


/« top row »/ 
/« left column »/ 
/« bottom row »/ 
/ right column x/ 


/« number of blank lines «/ 

/« pointer to cell to write »/ 

/« video handle »/ 
The VioScrollUp function scrolls the current screen upward. 
The VioScrollUp function is a family API function. 


usTopRow Specifies the top row of the screen area to scroll. 
usLeftCol Specifies the leftmost column of the screen area to scroll. 
usBotRow Specifies the bottom row of the screen area to scroll. 
usRightCol Specifies the rightmost column of the screen area to scroll. 


cbLines | Specifies the number of blank lines to insert at the bottom of the 
screen area being scrolled. If this parameter is zero, no lines are inserted. 


pbCell Points to a character/attribute pair, called a cell, that fills the screen 
area left blank by the scrolling. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


Comments 


Example 


~ See Also 


VioScrUnLock 
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ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


If the usTopRow and usLeftCol parameters are zero, they identify the upper- 
left corner of the screen. If you specify a value greater than the maximum for 
usTopRow, usLeftCol, usBotRow, usRightCol, or cbLines, the maximum value 
for that parameter is used. Maximum values depend upon the dimensions of the 
screen being used. 


You can use the VioScrollUp function to clear the screen by setting usTopRow 
and usLeftCol to zero and usBotRow, usRightCol, and cbLines to their maximum 
values. The function clears the screen by using the character/attribute pair 
pointed to by the pbCell parameter. 


This example calls VioScrollUp to scroll the entire screen up (by using the value 
OxFFFF for usBotRow, usRightCol, and cbLines) and to fill the screen area left 
blank by the scrolling with spaces on a green background (0x22 on an EGA 
color monitor): 


BYTE bCell[2]; 


bCell [0] = 0x20; /* space character */ 

bCell [1] = 0x22; /* green attribute (EGA) */ 

VioScrollUp (0, /* top row * 
oO, /* left column */ 
OxFFFE, /* bottom row */ 
OxEFFE, /* right column */ 
OxFFFE, _f* number of lines */ 
bCell, /* cell to write */ 
° /* video handle * 


ie 
VioSetCurPos(0O, O 0); 


VioScroliDn, VioScrollLf, VioScrollRt 


USHORT VioScrUnLock ( hvio) 
HVIO hvio; /« video handle «/ 


Parameters 


Return Value 


The VioScrUnLock function unlocks the screen previously locked by the pro- 
cess. 


The VioScrUnLock function is a family API function. 
hvio Identifies an advanced video-input-and-output (A VIO) presentation 


space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_UNLOCK 
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Example 


See Also 


M@ VioSetAnsi 


This example calls the VioScrLock function to lock the screen, then calls Vio- 
ScrUnLock to unlock the screen: 


USHORT fNotLocked; 
VioSerLock (LOCKIO_WAIT, &fNotLocked, 0); 


VioScrUnLock (0) ; 


VioScrLock 


USHORT VioSetAnsi( fAnsi, hvio) 


USHORT fAnsi; 
HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/x ANSI flag »/ 
/x video handle »/ 


The VioSetAnsi function enables or disables processing of ANSI escape 
sequences by setting or clearing the ANSI flag, which specifies whether the 
VioWrtTTY function processes ANSI escape sequences. 


When a screen group is started, ANSI processing is enabled for the screen 
group. 


fAnsi Specifies the ANSI flag, which determines whether ANSI processing is 
enabled or disabled. If this flag is ANSILON, ANSI processing is enabled. If the 
flag is ANSILOFF, ANSI processing is disabled. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_INVALID_HANDLE 


This example displays two identical strings. Before the first string is displayed, 
VioSetAnsi disables ANSI processing. As a result, the VioWrtTTY function dis- 
plays the ANSI escape sequences as characters. Before VioWrtTTY displays the 
second string, VioSetAnsi enables ANSI processing, and the string is displayed 
in inverse video (black characters on a white background): 


VioSetAnsi(ANSI_OFF, 0); /* disables ANSI processing */ 
VioWrtTTY ("\33 [7mHello Monee \ee LOM ONE 21, 0 

VioSetAnsi (ANSI_ON, 0); /* enables ANSI processing */ 
VioWrt TTY ("\33 [7mHello Wor 1d\33[om\n\r", 21, 0); 

VioGetAnsi 
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H VioSetCp 
USHORT VioSetCp(usReserved, idCodePage, hvio) 


USHORT usReserved; /« must be zero s/ 
USHORT idCodePage; /« code-page identifier »/ 
HVIO hvio; /« video handle »/ 


The VioSetCp function sets the code page for the current screen group. The 
code page defines the character set used to display characters on the screen. 


Parameters usReserved Specifies a reserved value; must be zero. 


idCodePage Specifies the code-page identifier. This parameter can be any 
code-page identifier specified in the codepage command line in the config.sys 
file. If this parameter is 0x0000, the function uses the system default code page. 
The following are the valid code-page numbers: 


Number Code page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_BAD_CP 
ERROR_VIO_LINVALID_HANDLE 
Example This example calls VioSetCp to set the current system code page to the standard 
United States code page: 
if (VioSetCp (0, /* must be zero */ 
437, /* code-page identifier yes 


0O)) € /* video handle 
VioWrtTTY ("Code page not specified in CONFIG.SYS\n\r", 39, 0); 


See Also DosSetCp, VioGetCp 


@ VioSetCurPos 
USHORT VioSetCurPos(usRow, usColumn, hvio) 


USHORT usRow; /» row position »/ 
USHORT usColumn; /« column position «/ 
HVIO hvio; /x video handle — «/ 


The VioSetCurPos function sets the screen position of the cursor. 
The VioSetCurPos function is a family API function. 
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Parameters usRow Specifies the row position of the cursor, where zero is the top row. 


usColumn Specifies the column position of the cursor, where zero is the left- 
most column. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


Example This example calls VioSetCurPos to place the cursor in the first column of the 
last row on the screen, and then displays the text “Hello World!”: 


VioSetCurPos (24, /7/* cursor row a/ 
te) /* cursor column */ 
0); /* video handle */ 

VioWrtTTY ("Hello World!", 12, 0); 


See Also VioGetCurPos, VioSetCurType 


VioSetCurType 


USHORT VioSetCurType( pvioci, hvio) 
PVIOCURSORINFO pvioci; /« pointer to structure for cursor characteristics »/ 
HVIO hvio; /« video handle (af 


The VioSetCurType function sets the cursor type. 


The cursor is a shared resource for all processes in a screen group. If one pro- 
cess changes it, it is changed for all processes in the group. 


The VioSetCurType function is a family API function. 


Parameters pvioci Points to the VIOCURSORINFO structure that specifies the character- 
istics of the cursor. The VIOCURSORINFO structure has the following form: 
typedef struct _VIOCURSORINFO { 
USHORT yStart; 
USHORT cEnd; 
USHORT cx; 
USHORT attr; 

} VIOCURSORINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_WIDTH 


Example This example calls VioSetCurType to set the current cursor type to a block cur- 
sor with 14 scan lines: 


VIOCURSORINFO vioci; 


vioci.yStart = O; /7* beginning scan line for cursor */ 
vioci.cEnd = 13; * ending scan line, zero-based a/ 
vioci.cx = O; /* default width, one character a/ 
vioci.attr = 0; * normal attribute * 


VioSetCurType (&vioci, 0); 


See Also VioGetCurType, VioSetCurPos 


VioSetDeviceCellSize 
USHORT VioSetDeviceCeliSize (cRows, cColumns, hvps) 


SHORT cRows; /« cell height «/ 
SHORT cCol/umns; /« cell width »/ 
HVPS hvps; /« presentation-space handle «/ 


The VioSetDeviceCellSize function sets the size of the device character cell. 


Parameters cRows Specifies the height (in pels) of the character cell. 
cColumns Specifies the width (in pels) of the character cell. 


hvps Identifies the advanced video-input-and-output (A VIO) presentation 
space. This handle must have been created previously by using the VioCreatePS 


function. 

Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

See Also VioCreatePS, VioGetDeviceCellSize 


VioSetFont 
USHORT VioSetFont( pviofi, hvio) 


PVIOFONTINFO pviofi; /« pointer to structure for display font «/ 
HVIO hvio; /x video handie »/ 


The VioSetFont function sets the font used to display characters on the screen. 
A font consists of several bitmaps, one for each character in a character set. 
The bitmaps define the character shapes. The font must be compatible with the 
current screen mode; that is, the bitmap size must match the current character- 
cell size. 


The VioSetFont function resets the current code page. A subsequent call to the 
VioGetCp function returns an error value. 


Not all display adapters permit the font to be set. 
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Parameters 


Return Value 


See Also 


VioSetMode 


pviofi Points to the VIOFONTINFO structure that specifies the display font. 
The VIOFONTINFO structure has the following form: 


typedef struct _VIOFONTINFO { 
USHORT cb; 
USHORT type; 
USHORT cxCell; 
USHORT cyCell; 
ULONG) pbData; 
USHORT cbData; 
} VIOFONTINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (AVIO) presentation © 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_LENGTH 
VioGetCp, VioGetFont 


USHORT VioSetMode ( pviomi, hvio 
PVIOMODEINFO pviomi; /« pointer to structure for screen mode «/ 


HVIO hvio; 


Parameters 


/« video handle »/ 


The VioSetMode function sets the screen mode. The screen mode defines the 
display mode (text or graphics), the number of colors being used (2, 4, or 16), 
and the width and height of the screen in both character cells and pels. VioSet- 
Mode also initializes the cursor position and type, but does not clear the screen. 


The VioSetMode function is a family API function. 


pviomi Points to the VIOMODEINEFO structure that specifies the screen 
mode. The VIOMODEINFO structure has the following form: 


typedef struct _VIOMODEINEFO { 
USHORT cb; 
UCHAR fbType; 
UCHAR color; 
USHORT col; 
USHORT row; 
USHORT hres; 
: USHORT vres; 
} VIOMODEINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 
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Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_LINVALID_LENGTH 
ERROR_VIO_MODE 


Comments Not all screen-mode values are valid for all displays. 

Example This example calls the VioGetMode function to retrieve the current display 
mode, changes the mode, and calls VioSetMode to enable the new display 
mode. 

VIOMODEINFO viomi; 

viomi.cbh = sizeof (viomi) ; 

VioGetMode(&viomi, 0); 

if (viomi.vres > 350) /* VGA display */ 
viomi.row = (viomi.row == 50) ? 25 : 50; 

else /* EGA display */ 
viomi.row = (viomi.row == 43) ? 25 : 43; 

VioSetMode(&viomi, O); 

See Also VioGetMode, VioSetState 

VioSetOrg 

USHORT VioSetOrg(sRow, sColumn, hvps) 

SHORT sAow; /« row number of cell a/ 

SHORT sCo/umn; /« column number of cell s/ 

HVPS hvps; /« presentation-space handle «/ 


The VioSetOrg function sets the origin for an advanced video-input-and-output 
(AVIO) presentation space. It moves the specified character cell to the upper- 
left corner of the screen. 


Parameters _ SRow Specifies the row number of the character cell that is to be the origin. 
sColumn — Specifies the column number of the character cell that is to be the 
origin. 


hvps Identifies the AVIO presentation space. This handle must have been 
created previously by using the VioCreatePS function. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value. 

See Also VioCreatePS, VioGetOrg 

VioSetState 


USHORT VioSetState ( pvoidState, hvio) 
PVOID pvoidState; —_/« pointer to buffer with new state «/ 
HVIO hvio; /« video handle _ «/ 


The VioSetState function sets the palette-register values, the overscan (border) 
color, or the blink/background intensity switch. 
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Parameters 


Return Value 


Example 


See Also 


pvoidState Points to the structure that contains the request type and the 
values to set. The structure type, which depends on the request type specified 
in the type fieid of each structure, is one of the foiliowing: VIOPALSTATE, 
VIOOVERSCAN, or VIOINTENSITY. These structures have the following 
forms: ate? 


typedef struct _VIOPALSTATE { 
USHORT cb; 
USHORT type; 
USHORT iFirst; 
USHORT acolor [1]; 
} VIOPALSTATE ; 


typedef struct _VIOOVERSCAN { 
USHORT cb; 
USHORT type; 
USHORT color; 

} VIOOVERSCAN; 


typedef struct _VIOINTENSITY { 
USHORT ch; 
USHORT type; 
USHORT fs; 

} VIOINTENSITY; 


Not all request-type values are valid for all screen modes. 
For a full description, see Chapter 4, “Types, Macros, Structures.” 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. : 


This example retrieves the current settings of the palette registers, switches 
palette registers #0 and #7, and calls VioSetState to enable the new settings: 


BYTE abState[38]; 

PVIOPALSTATE pviopal; 

USHORT usTmp; 

pviopal = (PVIOPALSTATE) abState; 
pviopal->cb = sizeof (abState) ; 


pviopal->type = 0; /* retrieves palette registers */ 
pviopal->iFirst = 0; /* first register to retrieve */ 
VioGetState(pviopal, 0); /* retrieves current settings */ 
usTmp = pviopal->acolor [0]; /* swaps# O and# 7 : * 


pviopal->acolor[O] = pviopal->acolor [7]; 
pviopal->acolor [7] usTmp ; 
VioSetState(pviopal, 0); /* enables new settings */ 


VioGetState, VioSetMode 
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— VioShowBuf 
USHORT VioShowBuf( offLVB, cbOutput, hvio) 


USHORT offLVB; /« offset into logical video buffer »/ 
USHORT cbOutput; /« length »/ 
HVIO hvio; /« video handle »/ 


The VioShowBuf function updates the physical screen from the logical video 
buffer (LVB). You may use the logical video buffer to directly manipulate infor- 
mation displayed on the screen. 


The VioShowBuf function is a family API function. 

Parameters offLVB Specifies the offset into the logical video buffer at which the screen 
update is to start. 
cbOutput Specifies the length (in bytes) of the screen area to update. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be the following: 


ERROR_VIO_LINVALID_HANDLE 


Example This example retrieves the address of the logical video buffer, makes changes to 
that buffer, and calls VioShowBuf to update the physical video buffer from the 
logical video buffer: 

PBYTE pbLVB; 


USHORT cbhOutput; 
VioGetBuf((PULONG) &pbLVB, &cbOutput, 0); 


VioShowBuf (0, ‘/* offset into logical video buffer */ 
cbhOutput, /* length of screen area 
0); /* video handle y 
See Also VioGetBuf, VioGetPhysBuf 


—@ VioShowPS 
USHORT VioShowPS (cRows, cColumns, off, hvps) 


SHORT cRows; /« height of rectangle »/ 
SHORT cColumns; /« width of rectangle »/ 
SHORT off; /« upper-left corner of rectangle «/ 
HVPS hvps; /« presentation-space handle _ «/ 


The VioShowPS function updates the display by copying all the latest changes in 
the specified rectangle to the display. 
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Parameters 


Return Value 


See Also 


cRows Specifies the height (in character cells) of the rectangle to update. 
cColumns Specifies the width (in character cells) of the rectangle to update. 


off Specifies the position of the upper-left corner of the rectangle to update. 
The position is relative to the first character cell in the advanced video-input- 
and-output (AVIO) presentation space. 


hvps Identifies the AVIO presentation space. This handle must have been 
created previously by using the VioCreatePS function. 


The return value is zero if the function is successful. Otherwise, it is an error 
value. 


VioCreatePS 

VioWrtCellStr , 

USHORT VioWrtCellStr(pchCeliString, cbCellString, usRow, usColumn, hvio) 

PCH pchCeliString; /« pointer to cell string »/ 

USHORT cbCellString; /» length of string s/ 

USHORT usRow; /» starting position (row) s/ 

USHORT usCo/umn; /« starting position (column) «/ 

HVIO hvio; /« video handle s/ 
The VioWrtCellStr function writes a cell string to the screen. A cell string is one 
or more character/attribute pairs. A character/attribute pair defines the charac- 
ter to be written and the character attribute by which it is displayed. 
If the string is longer than the current line, the function continues writing it at 
the beginning of the next line, but does not write past the end of the screen. 
The VioWrtCellStr function is a family API function. 

Parameters pchCellString Points to the cell string to write. 


Return Value 


cbCellString Specifies the length (in bytes) of the cell string. The length 
should be an even number. 


usRow Specifies the row at which to start writing the cell string. 
usColumn — Specifies the column at which to start writing the cell string. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


Example 


See Also 


VioWrtCharStr 
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This example calls the VioWrtCellStr function to display the string “Hello 
World!” using 12 different attributes: 


CHAR achCellString[] = “H\le\21\31\40\5 \6W\7o\10r\111\13d\14!"; 


VioWrtCellStr (achCellString, /* character/attribute string */ 
sizeof (achCellString) , /* length of string */ 
10, /* row */ 
35, /* column */ 
0); /* video handle / 


VioReadCellStr, VioWrtCharStr, VioWrtTTY 


USHORT VioWrtCharStr( pchString, cbString, usRow, usCo/lumn, hvio) 


PCH pchString; 
USHORT cbString; 
USHORT usRow; 
USHORT usCo/umn; 
HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/« pointer to string to write »/ 
/« length of character string »/ 
/« starting position (row) a/ 
/» starting position (column) «/ 
/x video handle a/ 


The VioWrtCharStr function writes a character string to the screen. A character 
string contains one or more character values, but no attributes. The function 
uses the present screen attributes to display the new characters. If the string is 
longer than the current line, the function continues writing it at the beginning of 
the next line but does not write past the end of the screen. 


The VioWrtCharStr function is a family API function. 


pchString Points to the character string to write. 

cbString Specifies the length (in bytes) of the character string. 
usRow Specifies the row at which to start writing the string. 
usColumn Specifies the column at which to start writing the string. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


This example calls VioWrtCharStr to display the string “Hello World!” on the 
screen at Row 12, Column 30: 


VioWrtCharStr ("Hello World!", /* string to display */ 
12, 


7* length of string */ 
12, /* row */ 
30, /* column */ 
O); /* video handle */ 


VioReadCharStr, VioWrtCharStr, VioWrtTTY 
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VioWrtCharStrAtt 


USHORT ViowrtCharStrAtt(pchString, cbString, usRow, usColumn, pbAttr, hvio) 


PCH pchString; 
USHORT cbString; 
USHORT usRow; 
USHORT usColumn; 
PBYTE pbAtir; 
HVIO hvio; 


Parameters 


Return Value 


Example 


See Also 


/« pointer to string to write «/ 
/« length of string «/ 
/« starting position (row) «/ 
/» starting position (column) «/ 
/« pointer to attribute s/ 
/« video handle »/ 


The VioWrtCharStrAtt function writes a character string to the screen, using the 
specified attribute. If the string is longer than the current line, the function con- 
tinues writing it at the beginning of the next line but does not write past the end 
of the screen. 


The VioWrtCharStrAtt function is a family API function. 


pchString Points to the character string to write. 

cbString Specifies the length (in bytes) of the character string. 
usRow Specifies the row at which to start writing the string. 
usColumn Specifies the column at which to start writing the string. 


pbAttr Points to the variable that specifies the attribute to be used for each 
character in the string. 


hvio Identifies an advanced video-input-and-output (AVIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_ROW 


This example calls VioWrtCharStrAtt to display the string “Hello World!” in the 
center of the screen in green characters on a white background (on an EGA 
color monitor): 


BYTE bhAttr = 0x72; /* green character, white background */ 

VioWrtCharStrAtt ("Hello World!", /* string to display */ 
12, /* length of string , &f 
12, /* row */ 
35, /* column */ 
&bhAttr, /* address of attribute */ 
O); /* video handle 7 


VioWrtCharStr, VioWrtNAttr, VioWrtTTY 
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@ VioWrtNAttr 
USHORT VioWrtNAttr( pbAttr, cb, usRow, usColumn, hvio) 


PBYTE pbAtir /« pointer to attribute to write «/ 
USHORT cb; /« number of times to write —+/ 
USHORT usRow; /» starting position (row) »/ 
USHORT usColumn; / starting position (column) »«/ 
HVIO hvio; /» video handle »/ 


The VioWrtNAttr function writes a character attribute to the screen a specified 
number of times. If the attribute is repeated more times than can fit on the 
current line, the function continues writing it at the beginning of the next line 
but does not write past the end of the screen. 


The VioWrtNAttr function is a family API function. 


Parameters pbAttr Points to the variable that specifies the character attribute to write. 
cb Specifies the number of times to write the character attribute. 
usRow Specifies the row at which to start writing the attribute. 
usColumn Specifies the column at which to start writing the attribute. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_INVALID_HANDLE 


ERROR_VIO_ROW 
Example This example calls VioWrtNAttr to change all the character attributes on the 
screen to green letters on a black background (on an EGA color monitor): 
BYTE bAttr = 0x02; /* green character, black background */ 
VioWrtNAttr (&bAttr, /* address of attribute a/ 
25 * 80, /* number of times to write attribute */ 
O, /* row a7 
O, /* column */ 
QO); /* video handle */ 
See Also VioWrtCharStrAtt, VioWrtNCell 


H VioWrtNCell 
USHORT VioWrtNCell(pbCel/, cb, usRow, usColumn, hvio) 


PBYTE pbCell; /« pointer to cell to write »/ 
USHORT cb; /« number of times to write »/ 
USHORT usRow; /« starting position (row) »/ 
USHORT usColumn; /x starting position (column) «/ 
HVIO hvio; /« video handle xf 


The VioWrtNCell function writes a cell to the screen a specified number of 
times. A cell (also called a character/attribute pair) consists of two unsigned 
byte values that specify the character and attribute to be written. 
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Parameters 


Return Value 


Example 


See Also 


VioWrtNChar 


If the number of times that a cell is repeated is greater than the screen width, 
the VioWrtNCell function continues writing the cell at the beginning of the next 
line but does not write past the end of the screen. 


The VioWrtNCell function is a family API function. 


pbCell Points to the cell to write. 

cb Specifies the number of times to write the cell. 

usRow Specifies the row at which to start writing the cell. 
usColumn Specifies the column at which to start writing the cell. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle. must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 
ERROR_VIO_ROW 


This example calls the VioWrtNCell function to fill the screen with green capital 
letter A’s (on an EGA color monitor): 


BYTE abCell[2]; /* character/attribute pair */ 
abCell[(O] = '‘A'; /7* character (letter A) */ 
abCell[{i] = 0x02; /* attribute (green) */ 
VioWrtNCell (abCell, /* address of attribute */ 
80 * 25, /7* number of cells to write */ 
O, /* row. ; */ 
oO, /* column */ 
QO); /* video handle a/ 
VioWrtNChar 


USHORT VioWrtNChar(pchChar, cb, usRow, usColumn, hvio) 


PCH pchChar; 
USHORT cb; 
USHORT usRow; 
USHORT usCo/umn; 


HVIO hvio: 


/« pointer to character to write «/ 
/« number of times to write «/ 


/« starting position (row) »/ 
/« starting position (column) — «/ 
/« video handle x/ 


The VioWrtNChar function writes a character to the screen a specified number 
of times. The function uses the present screen character attribute to display the 
new character. 


If the character is repeated more times than can fit on the current line, the 
VioWrtNChar function continues writing it at the beginning of the next line but 
does not write past the end of the screen. 


The VioWrtNChar function is a family API function. 
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Parameters pchChar Points to the character to write. 
cb Specifies the number of times to write the character. 
usRow Specifies the row at which to start writing the character. 
usColumn Specifies the column at which to start writing the character. 


hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 


Return Value The return value is zero if the function is successful. Otherwise, it is an error 
value, which may be one of the following: 


ERROR_VIO_COL 
ERROR_VIO_LINVALID_HANDLE 


ERROR_VIO_ROW 
Example This example calls the VioWrtNChar function to fill the screen with capital letter 
A’s: 
VioWrtNChar ("A", /* address of character */ 
80 * 25, /* number of characters to write */ 
O, /* row a7 
Oo, /* column */ 
0); /* video handle */ 
See Also VioWrtNCell 
VioWrtTTY 
USHORT VioWntTTY ( pchString, ebString, hvio) 
PCH pchString; /« pointer to string to write «/ 
USHORT cbString; /« length of string »/ 
HVIO hvio; /x video handle ; »/ 
The VioWrtTTY function writes a character string to the screen, starting at the 
current cursor position. This function advances the cursor as it writes each char- 
acter, using a default attribute for each character. If the function reaches the 
end of the line, it continues writing at the beginning of the next line. If it reaches 
the end of the last line on the screen, it scrolls the screen and continues writing 
at the beginning of a new line. 
The VioWrtTTY function is a family API function. 
Parameters pchString Points to the character string to write. 
cbString Specifies the length (in bytes) of the character string. 
hvio Identifies an advanced video-input-and-output (A VIO) presentation 
space. For AVIO programs, this handle must have been created previously using 
the VioCreatePS function. For other programs, hvio must be NULL. 
Return Value The return value is zero if the function is successful. Otherwise, it is an error 


value, which may be the following: 
ERROR_VIO_INVALID_HANDLE 
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Comments For some ASCII values, VioWrtTTY carries out an action rather than displaying 
| a character. The following list describes the action taken when the given ASCII 
byte Value is in the Str ing: 


Value Meaning 


0x08 BACKSPACE. Move the cursor left by one position, without 
deleting any character that is under the cursor. If the cursor is 
at the beginning of the line, take no action. 


0x09 TAB. Copy spaces from the current cursor position to the next 
tab stop. Tab stops are placed at every ee character posi- 
tion on a line. 


Ox0A LINEFEED. Move the cursor down to the next line. The screen 
will scroll up one line if the current line is at the bottom of the 
screen. 

Ox0D RETURN. Move the cursor to the beginning of the line. 

0x07 Bell. Generate a beep on the computer’s speaker. 


If the process has enabled ANSI processing by using the VioSetAnsi function, 
VioWrtITY processes any ANSI escape sequences in the string. 


Example The following example calls VioWrtTTY to write a ees to the screen and 
beep the computer’s speaker: | 


VioWrtTIy("File not found\r\n\007", 17, O); 


See Also VioSetCurPos, VioWrtCeliStr, VioWrtCharStr 
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3.1 Introduction 


This chapter describes the input-and-output control (IOCtl) functions. A pro- 
gram can send commands to and retrieve data from a device driver by using the 
DosDevIOCtl function. The DosDevIOCtl function sends the specified codes 
and data directly to the given device driver, which then carries out the specified 
action. 


IOCtl functions typically are used to get information about or data from a device 
driver that is not available through standard MS OS/2 functions. For example, 
IOCtl functions can be used to set the baud rate of a serial port or read input 
from a mouse. 


3.2 Category and Function Codes 


Each IOCtl function has a category and a function code. The category code 
defines the type of device to be accessed. MS OS/2 has several predefined 
categories. In general, all codes in the range 0x0000 through 0x007F are reserved 
for predefined categories. A device driver may also use additional categories, 
but these must be explicitly defined by the device and be in the range 0x0080 
through Ox00FF. The following list shows which devices correspond to the given 


categories: 
Category Device 
0x0001 Serial-device control 
0x0003 Screen/pointer-draw control 
0x0004 Keyboard control 
0x0005 Printer control 
0x0006 Light-pen control (Reserved) 
0x0007 Pointing-device (mouse) control 
0x0008 Disk/diskette control 
0x0009 Physical-disk control 
Ox000A Character-monitor control 
0x000B General device control 


The function code defines the action to carry out, such as reading from or writ- 
ing to the device and retrieving or setting the device modes. The number and 
meaning of each function code depend on the device driver and the specified 
category. Function codes range from 0x0000 through 0x001F and are combined 
with one or more of the following values: 


Value Meaning 


0x0020 Retrieve data or information from the device. If 0x0020 
is not part of the code, the function sends data or com- 
mands to the device. 
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Value Meaning 


0x0040 Pass the command to the device driver. If 0x0040 is not 
part of the code, MS OS/2 intercepts the command. 


0x0080 Ignore the command if the device driver does not sup- 
port it. If 0x0080 is not part of the code, the function 
returns an error code if the command is not supported. 


The following table lists the IOCtl functions by category and function codes and 
shows the corresponding function name: 


Table 3.1 Specific Category and Function Codes 


Serial-Device Control 


Category, Function Function name 

0x0001 ,0x0041 ASYNC_SETBAUDRATE 
0x0001,0x0042 ASYNC_SETLINECTRL 
0x0001 ,0x0044 ASYNC_TRANSMITIMM 
0x0001 ,0x0045 ASYNC_SETBREAKOFF 
0x0001 ,0x0046 ASYNC_SETMODEMCTRL 
0x0001 ,0x004B ASYNC_SETBREAKON 
0x0001 ,0x0047 ASYNC_STOPTRANSMIT 
0x0001 ,0x0048 ASYNC_STARTTRANSMIT 
0x0001 ,0x0053 ASYNC_SETDCBINFO 
0x0001,0x0061 ASYNC_GETBAUDRATE 
0x0001 ,0x0062 ASYNC_GETLINECTRL 
0x0001 ,0x0064 ASYNC_GETCOMMSTATUS 
0x0001 ,0x0065 ASYNC_GETLINESTATUS 
0x0001 ,0x0066 ASYNC_GETMODEMOUTPUT 
0x0001 ,0x0067 ASYNC_GETMODEMINPUT 
0x0001 ,0x0068 ASYNC_GETINQUECOUNT 
0x0001 ,0x0069 ASYNC_GETOUTQUECOUNT 
0x0001 ,0x006D ASYNC_GETCOMMERROR 
0x0001 ,0x0072 . ASYNC_GETCOMMEVENT 
0x0001 ,0x0073 ASYNC_GETDCBINFO 


Screen/Pointer-Draw Control 
Category, Function Function name 


0x0003, 0x0072 PTR_GETPTRDRAWADDRESS 


Keyboard Control 
Category, Function Function name 


0x0004 ,0x0050 KBD_SETTRANSTABLE 
0x0004 ,0x0051 KBD_SETINPUTMODE 


Table 3.1 (Continued) 


Category, Function 


0x0004,0x0052 
0x0004,0x0053 
0x0004,0x0054 
0x0004 ,0x0055 
0x0004 ,0x0056 
0x0004 ,0x0057 
0x0004,0x0058 
0x0004,0x005C 
0x0004,0x005D 
0x0004,0x005E 
0x0004,0x0071 
0x0004,0x0072 
0x0004,0x0073 


~ 0x0004 ,0x0074 


0x0004 ,0x0075 
0x0004,0x0076 
0x0004 ,0x0077 
0x0004 ,0x0078 
0x0004 ,0x0079 


Printer Control 


Category, Function 


0x0005,0x0042 
0x0005,0x0044 
0x0005,0x0046 
0x005,0x0048 
0x0005,0x0062 
0x0005,0x0064 
0x0005,0x0066 
0x0005,0x0069 
0x0005,0x006A 


. Function name 


KBD_SETINTERIMFLAG 
KBD_SETSHIFTSTATE 
KBD_SETTYPAMATICRATE 
KBD_SETFGNDSCREENGRP 
KBD_SETSESMGRHOTKEY 
KBD_SETFOCUS 
KBD_SETKCB 

KBD_SETNLS 
KBD_CREATE 
KBD_DESTROY 
KBD_GETINPUTMODE 
KBD_GETINTERIMFLAG 
KBD_GETSHIFTSTATE 
KBD_READCHAR 
KBD_PEEKCHAR 
KBD_GETSESMGRHOTKEY 
KBD_GETKEYBDTYPE 
KBD_GETCODEPAGEID 
KBD_XLATESCAN 


Function name 


PRT_SETFRAMECTL | 
PRT_SETINFINITERETRY 
PRT_INITPRINTER 
PRT_ACTIVATEFONT 
PRT_GETFRAMECTL 
PRT_GETINFINITERETRY 
PRT_GETPRINTERSTATUS 
PRT_QUTRYACTIVEFONT 
PRT_VERIFYFONT 


Pointing-Device (Mouse) Control 


Category, Function 


0x0007,0x0050 
0x0007,0x0051 
0x0007,0x0052 
0x0007,0x0053 
0x0007,0x0054 


Function name 


MOU_ALLOWPTRDRAW 
MOU_UPDATEDISPLA YMODE 
MOU_SCREENSWITCH | 
MOU_SETSCALEFACTORS 
MOU_SETEVENTMASK 
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Category, Function 


0x0007,0x0055 
0x0007 ,0x0056 
0x0007,0x0057 
0x0007 ,0x0058 
0x0007,0x0059 
0x0007,0x005A 
0x0007,0x005B 
0x0007,0x005C 
0x0007,0x0060 
0x0007 ,0x0061 
0x0007 ,0x0062 
0x0007 ,0x0063 
0x0007,0x0064 
0x0007,0x0065 
0x0007,0x0066 
0x0007 ,0x0067 
0x0007 ,0x0068 
0x0007,0x0069 


Disk/Diskette Control 


Category, Function 


0x0008,0x0000 
0x0008,0x0001 
0x0008,0x0002 
0x0008,0x0003 
0x0008,0x0020 
0x0008,0x0021 
0x0008,0x0043 
0x0008,0x0044 
0x0008,0x0045 
0x0008,0x0063 
0x0008,0x0064 
0x0008,0x0065 


Physical-Disk Control 


Category, Function 


0x0009,0x0000 
0x0009,0x0001 


Function name 


MOU_SETHOTKEYBUTTON 
MOU_SETPTRSHAPE 
MOU_DRAWPTR 
MOU_REMOVEPTR 
MOU_SETPTRPOS 
MOU_SETPROTDRAWADDRESS 
MOU_SETREALDRAWADDRESS 
MOU_SETMOUSTATUS 
MOU_GETBUTTONCOUNT 
MOU_GETMICKEYCOUNT 
MOU_GETMOUSTATUS | 
MOU_READEVENTQUE 
MOU_GETQUESTATUS 
MOU_GETEVENTMASK 
MOU_GETSCALEFACTORS 
MOU_GETPTRPOS 
MOU_GETPTRSHAPE 
MOU_GETHOTKEYBUTTON 


Function name 


‘DSK_LOCKDRIVE 


DSK_UNLOCKDRIVE 
DSK.REDETERMINEMEDIA 
DSK_SETLOGICALMAP 
DSK_BLOCKREMOVABLE 
DSK_GETLOGICALMAP 
DSK_SETDEVICEPARAMS 
DSK_WRITETRACK 
DSK_FORMATVERIFY 
DSK_GETDEVICEPARAMS 
DSK_READTRACK _ 
DSK_VERIFYTRACK 


Function name ._— 


PDSK_LOCKPHYSDRIVE 
PDSK_UNLOCKPHYSDRIVE 
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Table 3.1 (Continued) Category, Function Function name 


0x0009,0x0044 PDSK_WRITEPHYSTRACK 
0x0009,0x0063 PDSK_GETPHYSDEVICEPARAMS 
0x0009,0x0064 PDSK_READPHYSTRACK 
0x0009,0x0065 PDSK_VERIFYPHYSTRACK 


Character-Monitor Control 
Category, Function Function name 


0x000A ,0x0040 MON_REGISTERMONITOR 


General Device Control 


Category, Function Function name 


0x000B,0x0001 DEV_FLUSHINPUT 
0x000B ,0x0002 DEV_FLUSHOUTPUT 
0x000B ,0x0060 DEV_QUERYMONSUPPORT 


3.3 Functions 
This section lists the IOC#l functions in alphabetical order. Each function’s syn- 
tax is given and the parameters and return values are described. 
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am ASYNG _GETBAUDRATE 


USHORT DosDeviO0Ctl( pusBaudRate, OL, 0x0061. 0x0001. hDevice) 
PUSHORT pusBaudRate; /« pointer to variable for baud rate «/ 
HFILE hDevice; /» device handle »/ 


The ASYNC_GETBAUDRATE function retrieves the baud rate for the 
specified serial device. The baud rate specifies the number of bits per second 
that the serial device transmits or receives. 


Parameters pusBaudRate Points to the variable that receives the baud rate. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, ASYNC_SETBAUDRATE 


mM ASYNC_GETCOMMERROR 


USHORT DosDeviO0Ctl( pfCommErr, OL, 0x006D, 0x0001, hDevice) 
PUSHORT pfCommeErr; /» pointer to variable for error »/ 
HFILE hDevice; /« device handle «/ 


The ASYNC_GETCOMMERROR function retrieves the communication error 
word. After copying the error-word value to the specified variable, the function 
clears the error word. 


Parameters pfCommErr _ Points to the variable that receives the communication status of 
the device. This variable can be a combination of the following values: 


Value Meaning 


RX_QUE_OVERRUN Receive-queue overrun. There is no room 
in the device-driver receive queue to 
put a character read in from the receive 
hardware. 


RX_HARDWARE_OVERRUN Receive-hardware overrun. A character 


arrived before the previous character was 
completely read. The previous character is 


. lost. 
PARITY_ERROR . The hardware detected a parity error. 
FRAMING_ERROR The hardware detected a framing error. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful. When an error occurs, the 
function returns an error value, and any value copied to the variable pointed to 
by the pfCommErr parameter is not valid, and the function does not clear the 
error word. 


Comments 


See Also 
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Other than using this function, the only way to clear the communications error 
word for a device is to open the device when there are no outstanding open han- 
dles for it. For more information, see the ASYNC_SETDCBINFO function 
(0x0001, 0x0053). 


DosOpen, ASYNC_GETCOMMEVENT, ASYNC_GETCOMMSTATUS, 
ASYNC_SETDCBINFO 


ASYNC_GETCOMMEVENT 
USHORT DosDeviO0Ctl( pfEvent, OL, 0x0072, 0x0001, hDevice) 


PUSHORT pfEvent; 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/x pointer to variable for events «/ 
/«{ device handle »/ 


The ASYNC_GETCOMMEVENT function retrieves the communications event 
flags from the internally maintained event word. After the function copies the 
event flags to the specified variable, it clears the event word. 


pfEvent Points to the variable that receives the event flags. This variable can 
be a combination of the following values: 


Value Meaning 

CHAR_RECEIVED A character has been read from the serial-device 
receive hardware and placed in the receive queue. 

LAST_CHAR_SENT The last character in the device-driver transmit 


queue has been sent to the serial-device transmit 
hardware. This does not mean there is no data to 
send in any outstanding write requests. 


CTS_CHANGED The clear-to-send (CTS) signal has changed state. 

DSR_CHANGED The data-set-ready (DSR) signal has changed state. 

DCD_CHANGED The data-carrier-detect (DCD) signal has changed 
state. 

BREAK_DETECTED A break has been detected. 


ERROR_OCCURRED A parity, framing, or overrun error has occurred. 
An overrun can be a receive hardware overrun or a 
receive queue overrun. 


RI_DETECTED The trailing edge of the ring indicator (RI) has 
been detected. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


This function clears the event word only when it is successful. The event word 
remains unchanged until the device is fully closed (there are no outstanding open 
handles) and then reopened. 


DosOpen, ASYNC_GETCOMMSTATUS, ASYNC_GETCOMMERROR 
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m@ ASYNC_GETCOMMSTATUS 


USHORT DosDeviOCtl( pbStatus, OL, 0x0064, 0x0001. hDevice) 
PBYTE pbStatus; —_/« pointer to variable for status «/ _ 
HFILE hDevice; /x device handie »/ 


The ASYNC_GETCOMMSTATUS function retrieves the communication 
status of the specified device. 


Parameters pbStatus Points to the variable that receives the communication status. This 
variable can be a combination of the following values: 


Value Meaning 


TX_WAITING_FOR_CTS Transmission is waiting for the clear- 
to-send (CTS) signal to be turned 
on. For a full description, see the 
ASYNC_SETDCBINFO function 
(0x0001, 0x0053). 


TX_WAITING_FOR_DSR Transmission is waiting for the data- 
set-ready (DSR) signal to be turned 
on. For a full description, see the 
ASYNC_SETDCBINFO function 
(0x0001, 0x0053). 


TX_WAITING_FOR_DCD Transmission is waiting for the data- 
carrier-detected (DCD) signal to be 
turned on. For a full description, see 
the ASYNC_SETDCBINFO function 
(0x0001, 0x0053). 


TX_WAITING_FOR_XON Transmission is waiting because the 
XOFF character is received. For a full 
description, see the following “Com- 
ments” section. 


TX_WAITING_TO_SEND_XON Transmission is waiting because the 
XOFF character is transmitted. For a 
full description, see the following 
“Comments” section. 


TX_WAITING_WHILE_BREAK_ON Transmission is waiting because a 
break is being transmitted. For 
a full description, see the 
ASYNC_SETBREAKON 
function (0x0001, 0x004B). 


TX_WAITING_TO_SEND_IMM Character is waiting to transmit 
. immediately. For a full description, 

see the ASYNC_TRANSMITIMM 
function (0x0001, 0x0044). 

RX_WAITING_FOR_DSR Receive state is waiting for the data- 
set-ready (DSR) signal to be turned 
on. For a full description, see the 
ASYNC_SETDCBINFO function 
(0x0001, 0x0053). 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. — 


Return Value 


Comments 


See Also 
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The return value is zero if the function is successful or an error value if an error 
occurs. 


Transmit status indicates why transmission is not occurring, regardless of 
whether or not there is data to transmit. However, the device driver must be 
enabled for the given condition (for example, enabled for output handshaking 
for the modem-control signal) for the status to reflect that the device driver is 
waiting for the given condition to transmit. 


For example, TX_WAITING_FOR_CTS means that the device driver puts 
receive characters in the device-driver receive queue, the device driver is not 
waiting to transmit a character immediately, and characters from the device- 
driver transmit queue are not transmitted because the clear-to-send (CTS) signal 
for output handshaking is used and CTS does not have the proper value. 


The communication status can include TX_WAITING_TO_SEND_XON if the 
device driver is enabled for automatic transmit flow control (XON/XOFF) or 
if the ASYNC_STOPTRANSMIT function (0x0001, 0x0047) has been used 

to tell the device driver to function as if an XOFF character is received. The 
ASYNC_TRANSMITIMM function (0x0001, 0x0044) can still be used to 
transmit characters immediately. The device driver can still automatically 
transmit XON and XOFF characters due to automatic receive flow control 
(XON/XOFF) when the device driver is in this state. 


The communication status can include TX_WAITING_FOR_XON if the device 
driver is enabled for automatic receive flow control. When in this state, the 
ASYNC_TRANSMITIMM function (0x0001, 0x0044) can still be used to 
transmit characters immediately, and the device driver can still automatically 
transmit XON characters. 


DosOpen, ASYNC_GETCOMMEVENT, ASYNC_GETLINESTATUS, 
ASYNC_SETDCBINFO, ASYNC_STARTTRANGMIT, 
ASYNC_STOPTRANSMIT, ASYNC_TRANSMITTIMM 


ASYNC_GETDCBINFO 
USHORT DosDeviOCtl( pusDCB, OL, 0x0073, 0x0001, hDevice) 


PUSHORT pusDCB; 


HFILE hDevice; 


Parameters 


/ pointer to structure for device-control information «/ 
/x device handle s/ 


The ASYNC_GETDCBINFO function retrieves device-control block informa- 
tion. 


pusDCB Points to the DCBINFO structure that receives the device-control 
block information. The DCBINFO structure has the following form: 


typedef struct _DCBINFO { 
USHORT usWriteTimeout; 
USHORT usReadTimeout; 
BYTE bFlagsl 
BYTE bFlags2 
BYTE bFlags3 
BYTE bErrorReplacementChar; 
BYTE bBreakReplacementChar; 
BYTE bXONChar; 
BYTE bXOFEChar; 
} DCBINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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Return Value 


Comments 


See Also 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful. When an error occurs, the 
function returns an error value, and any data copied to the DCBINFO structure 
‘pointed to by the pusDCB parameter is not valid. 


To ensure that only valid values are set in the device-control block, the program 
should call the ASYNC_GETDCBINFO function to fill the block, and then 
modify the settings and call the ASYNC_SETDCBINFO function with the 
modified block. 


DosOpen, ASYNC_SETDCBINFO 


ASYNC_GETINQUECOUNT 


USHORT DosDeviOCtl( pcReceiveQue, OL, 0x0068, 0x0001, hDevice) 
PUSHORT pcReceiveQue; /» pointer to structure for character count «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/« device handle »/ 


The ASYNC_GETINQUECOUNT function retrieves the number of characters 
in the receive queue. 


pcReceiveQue Points to the RXQUEUE structure that receives the count of 
characters in the receive queue. The RXQUEUE structure has the following 
form: 
typedef struct _RXQUEUE { 

USHORT cbhChars; 


USHORT cbhQueue; 
} RXQUEUE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 


occurs. 


The device-driver receive queue is a memory buffer between the memory pointed 
to by the read-request packet and the receive hardware for this serial device. 
The application may not assume that there are no unsatisfied read requests if 
there are characters in the device-driver receive queue. The behavior of data 
movement between the read request and the receive queue may change from 
release to release of the device driver. Programs should not be written to have a 
dependency on this information. 


Programs should be written to be independent of the receive queue being a fixed 
size. The information in this field allows the application to get the size of the 
receive queue. The current size of the receive queue is approximately 1K but is 
subject to change. : 


The application should be written to avoid device-driver receive queue overruns 
by using an application-to-application block protocol with the system the applica- 
tion is communicating with. 


DosOpen, ASYNC_GETOUTQUECOUNT 
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™ ASYNC_GETLINECTRL 


USHORT DosDevliOCtl( pbLineCir/, OL, 0x0062, 0x0001, hDevice) 
PBYTE pbLineCtrl; /« pointer to structure for control settings «/ 
HFILE hDevice; /»« device handle «/ 


The ASYNC_GETLINECTRL function retrieves the line characteristics (stop 
bits, parity, data bits, break) for the specified device. 


Parameters pbLineCtrl Points to a LINECONTROL structure that receives the settings for 
the number of data bits, parity, and number of stop bits. The LINECONTROL 
structure has the following form: 


typedef struct _LINECONTROL { 
BYTE bDataBits; 
BYTE bParity; 
BYTE bStopBits; 
BYTE fbTransBreak; 
} LINECONTROL; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. . 
See Also DosOpen, ASYNC_SETLINECTRL 


™ ASYNC_GETLINESTATUS 


USHORT DosDeviOCtl( pbTransStatus, OL, 0x0065, 0x0001, hDevice) 
_PBYTE pbTransStatus; /« pointer to variable for status «/ 
HFILE hDevice; /» device handle »/ 


The ASYNC_GETLINESTATUS function retrieves the data-transmission status 
for the specified serial device. 


Parameters | = pbTransStatus Points to the variable that receives the data-transmission 
status. This variable can be a combination of the following values: 
Value Meaning 
WRITE_REQUEST_QUEUED Write-request packets in progress or 
queued. 
DATA_IN_TX_QUE Data in the device-driver transmit 
queue. 
HARDWARE_TRANSMITTING Transmit hardware currently transmit- 
ting data. 


CHAR_READY_TO_SEND_IMM Character waiting to be transmitted 
immediately. 
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Return Value 


See Also 


Value Meaning 

WAITING_TO_SEND_XON Waiting to automatically transmit 
XON 

WAITING_TO_SEND_XOFF Waiting to automatically transmit 
XOFF. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, ASYNC_GETCOMMSTATUS 


ASYNC_GETMODEMINPUT 
USHORT DosDevlOCtl( pbCtr/Signals, OL, 0x0067, 0x0001, hDevice) 


PBYTE pbCtriSignals; 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to variable for control signals «/ 
/« device handle s/ 


The ASYNC_GETMODEMINPUT function retrieves the modem-control input 
signals for the specified device. 


pbCtrlSignals Points to the variable that receives the modem-control signals. 
This variable can be a combination of the following values: 

Value - Meaning 

CTS_ON Clear-to-send (CTS) signal is on. If not given, the signal is off. 


DSR_ON Data-set-ready (DSR) signal is on. If not given, the signal is 
off. 
RILON Ring-indicator (RI) signal is on. If not given, the signal is off. 
DCD_ON Data-carrier-detect (DCD) signal is on. If not given, the signal 
is off. 
hDevice Identifies the serial device that receives the device-control function. 


The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. ; 


DosOpen, ASYNC_GETMODEMOUTPUT, ASYNC_SETMODEMCTRL 


ASYNC_GETMODEMOUTPUT 


- USHORT DosDeviOCtl( pbCtr/Signals, OL, 0x0066, 0x0001, hDevice) 


PBYTE pbCtriSignals; 


HFILE hDevice; 


/« pointer to variable for control signals «/ 
/« device handle x/ 


The ASYNC_GETMODEMOUTPUT function retrieves the modem-control out- 
put signals for the specified device. 


Parameters 


Return Value 


See Also 
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pbCtrlSignals Points to the variable that receives the modem-control signals. 
This variable can be one or both of the following values: 


Value Meaning 

DTR_ON Data-terminal-ready (DTR) signal is on. If not given, the signal 
is off. 

RTS_ON Request-to-send (RTS) signal is on. If not given, the signal is 
off. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, ASYNC_GETMODEMINPUT, ASYNC_SETMODEMCTRL 


ASYNC_GETOUTQUECOUNT 


USHORT DosDeviOCtl( pcTransmitQue, OL, 0x0069, 0x0001, hDevice) 
PUSHORT pcTransmitQue; /« pointer to structure for character count «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/» device handle »/ 


The ASYNC_GETOUTQUECOUNT function retrieves a count of characters in 
the transmit queue. 


pcTransmitQue Points to the RXQUEUE structure that receives the count of 
characters in the transmit queue. The RXQUEUE structure has the following 
form: 
typedef struct _RXQUEUE { 

USHORT cbChars; 


USHORT cbhQueuve; 
} RXQUEUE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


The device-driver transmit queue is a memory buffer between the memory 
pointed to by the write-request packet and the transmit hardware for this serial 
device. If the transmit queue is empty, the program may not assume that all 
write requests are completed or that no write requests are outstanding. The 
behavior of data movement between the write request and the transmit queue 
may change from release to release of the device driver. Programs should not be 
written to have a dependency on this information. 


Programs should be written to be independent of the transmit queue being a 
fixed size. The information in this field allows the application to get the size of 
the transmit queue. The current size of the transmit queue is approximately 128 
bytes but is subject to change. . 


DosOpen, ASYNC_GETINQUECOUNT 
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™ ASYNC_SETBAUDRATE 


USHORT DosDevlOCti( OL, pusBitRate, 0x0041, 0x0001, hDevice) 
PUSHORT pusBitRate; /« pointer to variable with baud rate «/ 
HFILE hDevice; /« device handle a/ 


The ASYNC_SETBAUDRATE function sets the baud rate for the specified 
serial device. The baud rate specifies the number of bits per second that the 
serial device transmits or receives. 


Parameters pusBitRate Points to the variable that contains the baud rate. This parameter 
can be any one of the following values: 110, 150, 300, 600, 1200, 2400, 4800, 
9600, or 19200. 


hDevice | Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if the 


specified baud rate is out of range or an error occurs. 
Comments The initial rate for a serial device is 1200 baud. Once the rate is set, it remains 
unchanged until set again, even if the device is closed and then reopened. 
See Also DosOpen, ASYNC_GETBAUDRATE 


m@ ASYNC_SETBREAKOFF 


USHORT DosDeviOCtI( pfCommeErr, OL, 0x0045, 0x0001, hDevice) 
PUSHORT pfCommErr, /« pointer to variable for error value «/ 
HFILE hDevice; /« device handle »/ 


The ASYNC_SETBREAKOFF function turns off the break character. The 
device driver stops generating a break signal. It is not considered an error if the 

_ device driver is not generating a break signal. The device driver then resumes 
transmitting characters, taking into account all the other reasons why it may or 
may not transmit characters. 


Parameters pfCommErr Points to the variable that receives the communication status of 
the device. This variable can be a combination of the following values: 


Value Meaning 


RX_QUE_OVERRUN Receive queue overrun. There is no room 
in the device-driver receive queue to 
put a character read in from the receive 
hardware. 


RX_HARDWARE_OVERRUN Receive hardware overrun. A character 
arrived before the previous character was 
completely read. The previous character is 


lost. 
PARITY_ERROR The hardware detected a parity error. 
FRAMING_ERROR The hardware detected a framing error. 


The function sets the variable to zero if it encounters an error. 


Return Value 


See Also 
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hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, ASYNC_SETBREAKON 


ASYNC_SETBREAKON 


USHORT DosDeviOCtl( pfCommeErr, OL, 0x004B, 0x0001, hDevice) 
PUSHORT pfCommErr; /» pointer to variable for error value «/ 


HFILE hDevice; 


Parameters 


Return Value 
Comments 


See Also 


/« device handle »/ 


The ASYNC_SETBREAKON function turns on the break character. The 
device driver generates the break signal immediately. It is not considered an 
error if the device driver is already generating a break signal. The device driver 
does not wait for the transmit hardware to become empty. However, more data 
will not be given to the transmit hardware until the break is turned off. The 
break signal will always be transmitted, regardless of whether the device driver is 
or is not transmitting characters due to other reasons. 


pfCommErr _ Points to the variable that receives the communication status of 
the device. This variable can be a combination of the following values: 


Value Meaning 


RX_QUE_OVERRUN Receive queue overrun. There is no room 
in the device-driver receive queue to 
put a character read in from the receive 
hardware. 


RX_HARDWARE_OVERRUN Receive hardware overrun. A character 
arrived before the previous character was 
completely read. The previous character is 


lost. 
PARITY_ERROR The hardware detected a parity error. 
FRAMING_ERROR The hardware detected a framing error. 


The function sets the variable to zero if it encounters an error. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


Closing the device turns off the break character if there are no outstanding open 
device handles. 


DosOpen, ASYNC_SETBREAKOFF 
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@ ASYNC_SETDCBINFO 
USHORT DosDeviOCtl( OL, pusDCB, 0x0053, 0x0001, hDevice) 


PUSHORT pusDCB; 
HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/« pointer to structure with device-control information »/ 
/« device handle »/ 


The ASYNC_SETDCBINFO function sets device-control block information. 


pusDCB Points to the DCBINFO structure that receives the device-control — 
block information. The DCBINFO structure has the following form: 


typedef struct _DCBINFO { 
USHORT usWriteTimeout; 
USHORT usReadTimeout; 
BYTE bFlagsl 
BYTE bFlags2 
BYTE bFlags3 
BYTE bErrorReplacementChar ; 
BYTE bBreakReplacementChar ; 
BYTE bXONChar; 
BYTE bXOFFChar; 
} DCBINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful. When an error occurs, the 
function returns an error value, and the device-control block characteristics of 
the device driver for this serial device remain unchanged. 


A program can prevent making unwanted changes to device modes by calling 
the ASYNC_GETDCBINFO function (0x0001,0x0073) to retrieve a copy of the 
current DCB. The program can then modify only those fields it needs to and 
use the modified DCB with the ASYNC_SETDCBINFO function. 


DosOpen, ASYNC_GETDCBINFO 


MH ASYNC_SETLINECTRL 
USHORT DosDeviOCtl( OL, pbLineCtri, 0x0042, 0x0001, hDevice) 


PBYTE pbLineCtr/; 
HFILE hDevice; 


Parameters 


/« pointer to structure with line settings «/ 
/« device handle ' »/ 


The ASYNC_SETLINECTRL function sets the line characteristics (stop bits, 
parity, and data bits) for the specified serial device. 


pbLineCtrl Points to the LINECONTROL structure that contains the 
settings for the number of data bits, parity, and number of stop bits. The 
LINECONTROL structure has the following form: 


typedef struct _LINECONTROL { 
BYTE bDataBits; 
BYTE bParity; 
BYTE bStopBits; 
BYTE fbTransBreak; 
} LINECONTROL; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if any of 
the specified line characteristics is out of range. When an error occurs, line 
characteristics remain unchanged. 


Comments When a device is first opened, the initial line characteristics are 7 data bits, 
even parity, and 1 stop bit. After line characteristics are changed, they remain 
changed until the function is used again, even if the device is closed and 
reopened. 


If the number of data bits is less than 8, the device driver fills with zeros the 
unused high-order bits of each character it receives from the device; the device 
driver ignores the unused high-order bits of characters it receives from the pro- 
gram. Therefore, if the number of data bits is 7 but the XOFF character is 0x80, 
the device driver does not recognize the XOFF character even when automatic- 
transmission control is enabled. If the error substitution character is 0x80, the 
device driver still places 0x80 in the receive queue. Programs must see that these 
characters match the specified data size. Any characters that were in the receive 
queue before the function is called remain unchanged. 


See Also DosOpen, ASYNC_GETLINECTRL 


ASYNC_SETMODEMCTRL 
USHORT DosDevlOCtl( pfCommeErr, pbCirlSignals, 0x0046, 0x0001, hDevice) 


PUSHORT pfCommeErr,; /« pointer to variable for error value x/ 
PBYTE pbCtriSignals; /» pointer to structure with control signals «/ 
HFILE hDevice; /» device handle x/ 


The ASYNC_SETMODEMCTRL function sets the modem-control signals. This 
function turns on or off the data-terminal-ready (DTR) and ready-to-transmit 
(RTS) signals (initially, the DTR and RTS signals are turned off). 


Parameters pfCommErr Points to the variable that receives the communication status of 
the device. This variable can be a combination of the following values: 


Value Meaning 


RX_QUE_OVERRUN Receive queue overrun. There is no room 
in the device driver receive queue to 
put a character read in from the receive 
hardware. 


RX_HARDWARE_OVERRUN Receive hardware overrun. A character 
arrived before the previous character was 
completely read. The previous character is 


lost. 
PARITY_ERROR The hardware detected a parity error. 
FRAMING_ERROR The hardware detected a framing error. 


The function sets the variable to zero if it encounters an error. 
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Return Value 


Comments 


See Also 


pbCtrlSignals Points to the MODEMSTATUS structure that contains the set- 
tings for the modem-control signals. The MODEMSTATUS structure has the fol- 
iowing form: 
typedef struct _MODEMSTATUS { 

BYTE fbModemOn; 


BYTE fbModemOff; 
} MODEMSTATUS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if the 
specified signal settings are invalid. When an error occurs, the signal settings 
remain unchanged. 


This function must not be used to enable or disable the DTR or RTS signal if 
the signal is being used for input handshaking or toggling on transmit. Any 
attempt to do so will cause a “general failure” error. 


Although the function copies the communication error status to the variable 
pointed to by the pfCommErr parameter, it does not clear the error. 


If the serial device is opened after having been closed, the DTR and RTS signals 
are set to the values specified by the DTR control mode and the RTS control 
mode, respectively. For a full description, see the ASYNC_SETDCBINFO 
function (0x0001,0x0053). 


After a serial device has been closed, the device driver turns off the DTR and 
RTS signals, but only after the device has transmitted all data and has waited for 
at least as long as it would take to transmit 10 additional characters. 


DosOpen, ASYNC_GETMODEMINPUT, ASYNC_GETMODEMOUTPUT 


ASYNC_STARTTRANSMIT 
USHORT DosDeviOCtl( OL, OL, 0x0048, 0x0001, Device) 


HFILE hDevice; 


Parameters 


Return Value 


/x device handle «/ 


The ASYNC_STARTTRANSMIT function starts transmission. This function 
allows data transmission to be resumed by the device driver if data transmission 
is halted due to the ASYNC_STOPTRANSMIT function (0x0001,0x0047) or due 
to an XOFF character being received while the device driver is in automatic 
transmit flow control mode. This function is similar to the device receiving the 
XON character. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 
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Comments There may be other reasons why transmission is disabled; transmission ma 
- not be resumed. For more information, see the ASYNC_GETCOMMSTATUS 
function (0x0001,0x0064). 


See Also DosOpen, ASYNC_GETCOMMSTATUS , ASYNC_STOPTRANSMIT 


™ ASYNC_STOPTRANSMIT 


USHORT DosDeviOCtl( OL, OL, 0x0047, 0x0001, hDevice) 
HFILE hDevice; /« device handle «/ 


The ASYNC_STOPTRANSM IT function stops the device from transmitting. 
This function stops data transmission by preventing the device driver from send- 
ing additional data to the transmit hardware. This function is similar to the 
device receiving the XOFF character. 


Parameters hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 
Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments If automatic-transmission control is enabled, this request causes the device 


driver to behave exactly as if it received the XOFF character. Transmission 
can be resumed if an XON character is received by the device driver, if an 
ASYNC_STARTTRANSMIT (0x0001,0x0048) function is received, or if the 
device driver is told to disable automatic-transmission control and in the previ- 
ous state automatic-transmission control was enabled. 


If automatic-transmission control is disabled, the ASYNC_STARTTRANSMIT 
function (0x0001,0x0048) must be called for transmission to resume. If, after this 
request is received, the device driver is told to enable automatic-transmission 
control, transmission is still disabled. It can be re-enabled by any of the 
scenarios discussed above. 


There still may be other reasons why transmission may be disabled. For more | 
information, see the ASYNC_GETCOMMSTATUS function (0x0001,0x0064). 


See Also. - DosOpen, ASYNC_GETCOMMSTATUS , ASYNC_STARTTRANSMIT 


mM ASYNC_TRANSMITIMM 


USHORT DosDevlOCtl( OL, pbChar, 0x0044, 0x0001, hDevice) 
PBYTE pbChar; /» pointer to character «/ 


FILE hDevice; /« device handle »/ 
The ASYNC_TRANSMITIMM function transmits the specified byte immedi- 
ately. 

Parameters pbChar Points to the character to be transmitted. 


hDevice Identifies the serial device that receives the device-control function. 
The handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


274. ASYNC_TRANSMITIMM 


Comments 


See Also 


The device driver queues the character as the next character to be transmitted 
even if there are already characters in the transmit queue. 


If automatic-receiving control is enabled, an XON or XOFF character may be 
transmitted before the requested character. 


The function always returns before the character is actually transmitted. 


If a character is already waiting to be transmitted immediately, the function 
returns an error. The ASYNC_LGETCOMMSTATUS function (0x0001,0x0064) 
can be used to determine whether a character is currently waiting to be transmit- 
ted immediately. 


The device driver will not immediately transmit the character that is waiting to 
be transmitted immediately if the device driver is not transmitting characters due 
to modem-control signal-output handshaking or if the device driver is currently 
transmitting a break. 


_If the device driver is not transmitting characters due to automatic transmission 


or receiving control (XON/XOFF) being enabled or due to operating as if an 
XOFF character had been received, the device driver still transmits a character 
that is waiting to be transmitted immediately due to this request. An application 
that requests that the device driver transmit a character immediately if automatic 
transmission or receiving control is enabled may cause unexpected results to 
happen to the communications line flow control protocol. 


This function is generally used to manually send XON and XOFF characters. 


The character waiting to be transmitted immediately is not considered part of 
the device driver transmit queue and is not flushed due to a flush request. 
XON/XOFF characters that are automatically transmitted due to automatic- 
receiving control may or may not be placed ahead of the character waiting to be 
transmitted immediately. Applications should not be dependent on this ordering. 


DosOpen, ASYNC_GETCOMMSTATUS 


DEV _FLUSHINPUT 


USHORT DosDevi0Ctl(OL, pbCommand, 0x0001, 0x000B, hDevice) 


PBYTE pbCommand; 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to variable with command :/ - 
/» device handle s/ 


The DEV_FLUSHINPUT function flushes the input buffer. 


pbCommand Points to the variable that contains a reserved value. This value 
must be zero. 


hDevice Identifies the device that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, DEV_FLUSHOUTPUT 
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mM DEV_FLUSHOUTPUT 


USHORT DosDeviOCtl( OL, pbCommand, 0x0002, 0x000B, hDevice) 
PBYTE pbCommand; /« pointer to variable with command «/ 
HFILE hDevice; /x device handle * »/ 


The DEV_FLUSHOUTPUT function flushes the output buffer. 


Parameters pbCommand Points to the variable that contains a reserved value. This value 
must be zero. 


hDevice Identifies the device that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, DEV_FLUSHINPUT 


mM DEV_QUERYMONSUPPORT 


USHORT DosDeviO0Cti(OL, pb>Command, 0x0060, 0x000B, hDevice) 
PBYTE pbCommand; /« pointer to variable with command «/ 


HFILE hDevice; /« device handle x/ 
The DEV_QUERYMONSUPPORT function queries a device driver for monitor 
support. 

Parameters pbCommand Points to the variable that contains a reserved value. This value 


must be zero. 


hDevice Identifies the device that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the device supports character monitors or an error 
value if an error occurs. 


See Also DosOpen 


™@ DSK_BLOCKREMOVABLE 


USHORT DosDevlOCtl(pfNonRemovable, pbCommand, 0x0020, 0x0008, hDevice) 
PBYTE pfNonRemovable; /« pointer to removable/nonremovable flag «/ 


PBYTE pbCommand; /« pointer to variable with command »/ 

HFILE hDevice; /« device handle »/ 
The DSK_BLOCKREMOVABLE function indicates whether the block device is 
removable. 

Parameters pfNonRemovable Points to the variable that receives the medium type. This 


variable is 0x0000 if the medium is removable or 0x0001 if it is nonremovable. 


pbCommand Points to the variable that contains a reserved value. This value 
must be zero. 
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Return Value 


See Also 


hDevice Identifies the disk-drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. . 


DosOpen 


DSK_FORMATVERIFY 
USHORT DosDeviOCtl( OL, p>Command, 0x0045, 0x0008, hDevice) 


PBYTE pbCommand; 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/« pointer to structure with command «/ 
/« device handle »/ 


The DSK_FORMATVERIFY function formats and verifies a track on a disk 
drive according to the information passed in the format table. The format table 
is passed to the controller and the controller performs whatever operations are 
necessary for formatting. 


pbCommand Points to the TRACKFORMAT structure that contains informa- 
tion about the format operation. The TRACKFORMAT structure has the follow- 
ing form: . 


typedef struct _TRACKFORMAT { 
BYTE bCommand; 
USHORT head; 
USHORT cylinder; 
USHORT reserved; 
USHORT cSectors; 
struct { 
BYTE bCylinder; 
BYTE bHead; 
BYTE idSector; 
BYTE bBytesSector; 
} FormatTable[1]; 
} TRACKEORMAT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hDevice Identifies the disk-drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


Some controllers do not support formatting tracks with varying sector sizes. The 
program must make sure that the sector sizes specified in the format table are all 
the same. | 


DosOpen 
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— DSK_GETDEVICEPARAMS 
USHORT DosDeviOCtl( pbBPB, pbCommand, 0x0063, 0x0008, hDevice) 


PBYTE pb&PB; /« pointer to structure for BIOS parameter blocks «/ 
PBYTE pbCommand; /« pointer to variable with command »/ 
HFILE hDevice; /« device handle »/ 


The DSK_GETDEVICEPARAMS function retrieves the device parameters for 
an MS OS/2 block device. The device driver maintains two BIOS parameter 
blocks (BPB) for each disk drive. One block corresponds to the medium 
currently in the disk drive. The other is a recommended BPB, based on the type 
of medium that corresponds to the physical device. For example, a high-density 
disk drive has a BPB for a 96 tracks-per-inch (tpi) floppy disk; a low-density disk 
drive has a BPB for a 48-tpi floppy disk. 


Parameters pbBPB Points to the BIOSPARAMETERBLOCK structure that receives the 
BPB. The BIOSPARAMETERBLOCK structure has the following form: 


typedef struct _BIOSPARAMETERBLOCK { 
USHORT usBytesPerSector; 
BYTE bSectorsPerCluster; 
USHORT usReservedSectors; 
BYTE cFATs; 
USHORT cRootEntries; 
USHORT cSectors; 
BYTE bMedia; 
USHORT usSectorsPerFAT; 
USHORT usSectorsPerTrack; 
USHORT cHeads; 
ULONG cHiddenSectors; 
ULONG cLargeSectors; . 
USHORT cCylinders; 
BYTE bDeviceType; 
USHORT fDeviceAttr; 

} BIOSPARAMETERBLOCK; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pbCommand Points to the variable that specifies which BPB to retrieve. If 
the variable is 0x0000, the function retrieves the recommended BPB for the drive 
(the BPB for the physical device). If the variable is 0x0001, the function retrieves 
the BPB for the medium currently in the drive. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, DSK_SETDEVICEPARAMS 


—™@ DSK_GETLOGICALMAP 
USHORT DosDevliOCtI( pbDrive, pbCommand, 0x0021, 0x0008, hDevice) 


PBYTE pbDrive; /x pointer to variable for drive number «/ 
PBYTE pbCommand; /« pointer to variable with command = «/ 
HFILE hDevice; /x device handle »/ 


The DSK_GETLOGICALMAP function retrieves the mapping of a logical 
drive. 
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Parameters pbDrive Points to the variable that receives the logical-drive number. This can 
be 1 for drive A, 2 for drive B, and so on. The function sets the variable to zero 
if only one iogicai drive is mapped to the physicai drive. 


pbCommand Points to a variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the physical device that receives the device-control func- 
‘tion. The handle must have been created previously by using the DosOpen func- 


tion. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, SETLOGICALMAP 

DSK_LOCKDRIVE 


USHORT DosDeviOCtl( OL, pbCommand, 0x0000, 0x0008, hDevice) 
PBYTE pbCommand; /« pointer to variable with command «/ 
HFILE hDevice; /« device handle »/ 


The DSK_LOCKDRIVE function locks a disk drive, preventing file I/O by 
another process on the volume in the disk drive. This function succeeds if there 
is only one file handle open on the volume in the disk drive because the desired 
result is to exclude all other I/O to the volume. 


Parameters pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error. 
occurs. 

See Also DosOpen, DSK_UNLOCKDRIVE 

DSK_READTRACK 

USHORT DosDeviOCtl( pbBuffer, pbCommand, 0x0064, 0x0008, hDevice) 

PBYTE pbBuffer; /« pointer to buffer for data »/ 

PBYTE pbCommand; /« pointer to structure with command «/ 

HFILE hDevice; /« device handle »/ 


The DSK_READTRACK function reads from a track on a specified disk drive. 
The track table passed in the call determines the sector number, which is passed 
to the disk controller for the operation. When the sectors are odd-numbered or 
nonconsecutive, the request is broken into an appropriate number of single- 
sector operations, and one sector at a time is read. 


Parameters pbBuffer Points to the buffer that receives data read from the track. 


Return Value 
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pbCommand Points to the TRACKLAYOUT structure that contains the infor- 
mation about the read operation. The TRACKLAYOUT structure has the follow- 
ing form: 


typedef struct _TRACKLAYOUT { 
BYTE bCommand; 
USHORT head; 
USHORT cylinder; 
USHORT firstSector; 
USHORT cSectors; 
struct { 
USHORT sectorNumber; 
USHORT sectorSize; 
} TrackTable([1j; 
} TRACKLAYOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


Comments The device driver will not correctly read sectors of sizes other than 512 bytes if 
reading would generate a direct-memory-access (DMA) violation error. Programs 
must ensure that this error does not occur. 

See Also DosOpen, DSK_WRITETRACK 

DSK_REDETERMINEMEDIA 


USHORT DosDeviOCti( OL, p>Command, 0x0002, 0x0008, hDevice) 


PBYTE pbCommand; 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to variable with command »«/ 
/« device handle »/ 


The DSK_.REDETERMINEMEDIA function redetermines the media on a 
block device and updates the volume in the drive. This function is normally 
issued after the volume identification information has been changed (for exam- 
ple, by formatting the disk). This function should be called only if the volume is 
locked. 


pbCommand _ Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen 
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™ DSK_SETDEVICEPARAMS 
USHORT DosDeviOCtl( pbBPB, pbCommand, 0x0043, 0x0008, hDevice) 


PBYTE pbBPB; 
PBYTE pbCommand; 
HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to structure with BIOS parameter blocks «/ 
/« pointer to buffer with command »/ 
/x device handle »/ 


The DSK_SETDEVICEPARAMS function sets the device parameters for an 
MS OS/2 block device. The device driver maintains two BIOS parameter blocks 
(BPB) for each disk drive. One block is the BPB that corresponds to the 
medium currently in the disk drive. The other block is a recommended BPB, 
based on the type of medium that corresponds to the physical device. For exam- 
ple, a high-density disk drive has a BPB for a 96 tracks per inch (tpi) floppy 
disk; a low-density disk drive has a BPB for a 48-tpi floppy disk. 


PbBPB Points to the BIOSPARAMETERBLOCK structure that contains the 
device parameters to be set for the drive. The BIOSPARAMETERBLOCK 
structure has the following form: 


typedef struct _BIOSPARAMETERBLOCK { 
USHORT usBytesPerSector; 
BYTE bSectorsPerCluster; 
USHORT usReservedSectors; 
BYTE cFATs; 
USHORT cRootEntries; 
USHORT cSectors; 
BYTE bMedia; 
USHORT usSectorsPerFAT; 
USHORY usSectorsPerTrack; 
USHORT cHeads; 
ULONG cHiddenSectors; — 
ULONG cLargeSectors; 
USHORT cCylinders; 
BYTE bDeviceType; 
USHORT fDeviceAttr; 

} BIOSPARAMETERBLOCK; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
pbCommand Point to the variable that contains the command description. 
This variable can be one of the following values: 

Value Meaning 


BUILD_BPB_FROM_MEDIUM Build the BIOS parameter block (BPB) 
from the medium for all subsequent 
build BPB requests. 


REPLACE_BPB_FOR_DEVICE Change the default BPB for the physical 
device. 

REPLACE_BPB_FOR_MEDIUM Change the BPB for the medium to the 
specified BPB. Return the new BPB as 
the BPB for the medium for all subse- 
quent build BPB requests. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, DSK_GETDEVICEPARAMS 
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@ DSK_SETLOGICALMAP 
USHORT DosDevlOCtl( pbDrive, pbCommana, 0x0003, 0x0008, hDevice) 


PBYTE pbDrive; /« pointer to variable with drive number »/ 
PBYTE pbCommand; /« pointer to variable with command — :/ 
HFILE hDevice; /« device handle »/ 


The DSK_SETLOGICALMAP function sets the logical-drive mapping for a 
block device. 


Parameters pbDrive Points to the variable that contains the logical-drive number. This can 
be 1 for drive A, 2 for drive B, and so on. When the function returns, it copies 
the specified drive’s current logical-drive number to the variable. If only one log- 
ical device is mapped to the physical drive, the function sets the variable to zero. 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, DSK_GETLOGICALMAP 


m@ DSK_UNLOCKDRIVE 


USHORT DosDeviO0Cti( OL, pb>Command, 0x0001, 0x0008, hDevice) 
PBYTE pbCommand; /« pointer to variable with command »/ 
HFILE hDevice; /« device handle af 


The DSK_UNLOCKDRIVE function unlocks a drive. The drive requires the 
locked volume represented by the handle. 


Parameters pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, DSK_LOCKDRIVE 


mM DSK_VERIFYTRACK 


USHORT DosDeviOCti( OL, pb>Command, 0x0065, 0x0008, hDevice) | 
PBYTE pbCommand; /« pointer to structure with command «/ 
HFILE hDevice; /x device handle »/ 


The DSK_VERIFYTRACK function verifies an operation on a specified disk 
drive. 
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Parameters 


Return Value 


pbCommand Points to the TRACKLAYOUT structure that contains informa- 
tion about the verification operation. The TRACKLAYOUT structure has the fol- 


low ing for Pi: 


typeder struct _TRACKLAYOUT { 
BYTE bCommand; 
USHORT head; 
USHORT cylinder; 
USHORT firstSector; 
USHORT cSectors; 
struct { 
USHORT sectorNumber; 
USHORT sectorSize; 
} TrackTable([1]; 
} TRACKLAYOUT; : 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


Comments The track-layout table passed in the function determines the sector number, 
which is passed to the disk controller. When the sectors are odd-numbered or 
nonconsecutive, the request is broken into an appropriate number of single- 
sector operations, and one sector at a time is verified. 

See Also DosOpen, DSK_READTRACK, PDSK_VERIFYPHYSTRACK, 

. DSK_WRITETRACK 

DSK_WRITETRACK 

USHORT DosDevlOCtI( pbBuffer, pbCommand, 0x0044, 0x0008, Device) 

PBYTE pbBuffer; /x pointer to buffer with data x/ 

PBYTE pbCommand; /« pointer to structure with command «/ 

HFILE hDevice; /« device handle »/ 


Parameters 


The DSK_WRITETRACK function writes to a track on a specified disk drive. 


pbBuffer Points to the buffer that contains the data to be written. 


pbCommand Points to the TRACKLAYOUT structure that contains informa- 
tion about the write operation. The TRACKLAYOUT structure has the following 
form: 


typedef struct _TRACKLAYOUT { 
BYTE bCommand; 
USHORT head; 
USHORT cylinder; 
USHORT firstSector; 
USHORT cSectors; 
struct 
USHORT sectorNumber; 
USHORT sectorSize; 
} TrackTable[i1]; 
} TRACKLAYOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments The track-layout table passed in the function determines the sector number, 


which is passed to the disk controller. When the sectors are odd-numbered or 
nonconsecutive, the request is broken into an appropriate number of single- 
sector operations, and one sector at a time is written. 


See Also DosOpen, DSK_READTRACK, PDSK_READPHYSTRACK, 
PDSK_WRITEPHYSTRACK 


KBD_CREATE 


USHORT DosDeviOCtl( OL, pb>Command, 0x005D, 0x0004, hDevice) 
PBYTE pbCommand; /« pointer to buffer with handie and pid »/ 
HFILE hDevice; /« device handle x/ 


The KBD_CREATE function allocates memory for a logical keyboard (KCB). 
This function obtains physical memory for a new logical keyboard. The process 
ID and a logical-keyboard handle passed by the caller stored in allocated 
memory for use later by the KBD_SETKCB function. A logical keyboard is not 
created if the handle is zero. 


Parameters pbCommand Points to the buffer that contains the value to use as the logical- 
keyboard handle and the code-page identifier to use with the logical keyboard. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value ‘The return value is zero if the function is successful or an error value if the logi- 
cal keyboard cannot be created. 
See Also KBD_SETKCB, KBD_DESTROY 


KBD_DESTROY 


USHORT DosDevi0Ctl( OL, pbCommand, 0x005E, 0x0004, hDevice) 
PBYTE pbCommand; /« pointer to buffer with handle and pid «/ 
HFILE hDevice; /x device handle x/ 


The KBD_DESTROY function frees memory for a logical keyboard (KCB). 
This function searches for the existing logical keyboard that has the specified 
logical-keyboard handle and process ID combination and frees the physical 
memory associated with the logical keyboard. No action is taken if the specified 
handle is zero. . 


Parameters pbCommand Points to the buffer that contains the logical-keyboard handle. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 
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Return Value The return value is zero if the function is successful or an error value if the logi- 
cal keyboard identified by the given handle cannot be found. 
See Also KBD_CREATE 


KBD_GETCODEPAGEID 


USHORT DosDevlOCti( pbCPID, OL, 0x0078, 0x0004, hDevice) 
PBYTE pbCPID; /« pointer to buffer for code page id »/ 
HFILE hDevice; /« device handle s/ 


The KBD_GETCODEPAGEID function retrieves the identifier of the code page 
being used by the current logical keyboard. 


Parameters pbCPID Points to the CPID structure that receives the code-page identifier. 
The CPID structure has the following form: 
typedef struct _CPID { 
USHORT idCodePage; 


; USHORT Reserved; 
} CPID; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The © 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

Comment This function sets the identifier to zero to indicate that PC US 437 is being used. 

See Also KbdGetCp 


KBD_GETINPUTMODE 


USHORT DosDeviOCti( pbinputMode, OL, 0x0071, 0x0004, hDevice) 
PBYTE pbinputMode; /« pointer to variable for input mode »+/ 
HFILE hDevice; /« device handle »/ 


The KBD_GETINPUTMODE function retrieves the input mode of the screen 
group of the active process. The input mode defines whether the following keys 
are processed as commands or as keystrokes: CONTROL+C, CONTROL+BREAK, 
CONTROL+S, CONTROL+P, SCROLL LOCK, PRINTSCREEN. 


Parameters pbInputMode Points to the variable that receives the input mode. If the vari- 
able is ASCIT_MODE, the keyboard has ASCII input mode. If the variable is 
BINARY_MODE, the keyboard has binary input mode. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, KBD_SETINPUTMODE 
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™@ KBD_GETINTERIMFLAG 


USHORT DosDeviOCtl( pfFiags, OL, 0x0072, 0x0004, hDevice) 
PBYTE pfFlags; /» pointer to variable for flags »/ 
HFILE hDevice; /« device handle »/ 


The KBD_GETINTERIMFLAG function retrieves interim character flags. 


Parameters pfFlags Points to the variable that receives interim flags. If the variable is 
CONVERSION_REQUEST,, the program requested conversion. If it is 
INTERIM_CHAR, the interim console flag is set. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, KBD_SETINTERIMFLAG 


™@ KBD_GETKEYBDTYPE 


USHORT DosDeviOCtl( pbType, OL, 0x0077, 0x0004, hDevice) 
PBYTE pbType; /« pointer to structure for keyboard type «/ 


HFILE hDevice; /x device handle x/ 
The KBD_GETKEYBDTYPE function retrieves information about the type of 
keyboard being used. . 

Parameters pbType Points to the KBDTYPE structure that receives the keyboard type. 


The KBDTYPE structure has the following form: 


typedef struct _KBDTYPE { 
USHORT usType; 
USHORT reservedl1; 
USHORT reserved2; 

} KBDTYPE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen 


—™ KBD_GETSESMGRHOTKEY 


USHORT DosDevlOCtl( pbHotKeyBuf, pcHotKeys, 0x0076, 0x0004, hDevice) 
PBYTE pbHotKeyBuf; /« pointer to structure for hot-key information +/ 
PUSHORT pcHotKeys; /» pointer to variable for hot-key count »/ 
HFILE hDevice; /« device handle »/ 


The KBD_GETSESMGRHOTKEY function retrieves the hot-key information 
structures for the currently defined hot keys. 
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Parameters 


Return Value 


Comments 


See Also 


pbH otKeyBuf Points to the HOTKEY structure that receives hot-key informa- 


tion structures. The buffer must be at least as large as the number of structures 
requested. The HOATRRY ctructure has the following form: 
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typedef struct _HOTKEY { 
USHORT fHotKey; 
UCHAR scancodeMake; 
UCHAR scancodeBreak; 
USHORT idHotKey; 

} HOTKEY; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcHotKeys Points to the variable that specifies the number of hot-key infor- 
mation structures to retrieve. If this variable is HOTKEY_MAX_COUNT, the 
function copies a value to the variable that specifies the maximum number 

of hot keys the keyboard device driver can support. If this variable is 
HOTKEY_CURRENT_COUNT,, the function copies a value to this variable 
that specifies the actual number of hot keys currently supported. The function 
also copies the hot-key information to the buffer pointed. to by the pbHotKeyBuf 
parameter. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


If the variable pointed to by pcHotKeys is HOTKEY_MAX_COUNT, the func- 
tion returns the number of currently defined hot keys. The program uses this 
number to allocate sufficient space to retrieve the actual hot-key information 
(retrieved by setting the variable to HOTKEY_CURRENT_COUNT). 


Programs should retrieve the number of hot keys first, allocate sufficient space 
for the buffer pointed to by the pbHotKeyBuf parameter, then retrieve the hot 
keys. 


DosOpen, KBD_SETSESMGRHOTKEY 


KBD_GETSHIFTSTATE 
USHORT DosDevlOCtl( pbShiftState, OL, 0x0073, 0x0004, hDevice) 


PBYTE pbShiftState; 


HFILE hDevice; 


Parameters 


/« pointer to structure for shift state «/ 
/x device handle »/ 


The KBD_GETSHIFTSTATE function retrieves the shift state of the default 
keyboard of the current screen group. The shift state identifies whether the 
SHIFT, CONTROL, ALT, INSERT, and SYSREQ keys are up or down and whether 
the SCROLL LOCK, NUMLOCK, CAPSLOCK, and INSERT modes are on. 


pbShiftState Points to the SHIFTSTATE structure that receives the shift state. 
The SHIFTSTATE structure has the following form: 
typedef struct _SHIFTSTATE { 

USHORT fsState; 


BYTE fbNLS; 
} SHIFTSTATE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

Comments The shift state is set by incoming keystrokes. It can also be set by using the 
KBD_SETSHIFTSTATE function (0x0004, 0x0053). 

See Also DosOpen, KBD_SETSHIFTSTATE 


KBD_PEEKCHAR 


USHORT DosDeviOCtl{ pkkiBuffer, pusStatus, 0x0075, 0x0004, hDevice) 
PKBDKEYINFO pkkiBuffer; /« pointer to structure for keystroke «/ 
PUSHORT pusStatus; /« pointer to variable for status x/ 
HFILE hDevice; /« device handle «/ 


The KBD_PEEKCHAR function retrieves one character data record from the 
head of the keyboard-input buffer of the screen group of the active process. The 
character data record is not removed from the keyboard-input buffer. 


Parameters pkkiBuffer Points to the KBDKEYINFO structure that contains keyboard 
input. The KBDKEYINFO structure has the following form: 


typedef struct _KBDKEYINFO { 
UCHAR chChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNisShift; 
USHORT fsState; 
ULONG time; 
} KBDKEYINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pusStatus Points to the variable that receives the keyboard status. It can be 
one or both of the following values: 


Value Meaning 
KBD_DATA_RECEIVED Character data record is retrieved. If not set, 
no character data was retrieved. 
KBD_DATA_BINARY Input mode is binary. If not set, input mode 
is ASCII. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments If the shift-reporting input mode is enabled, the keystroke information retrieved 


may specify only a shift-state change and no character input. 


See Also DosOpen, KBD_READCHAR 
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m™ KBD_READCHAR 


USHORT DosDeviOCtl( pkkiBuffer, pcRecords, 0x0074, 0x0004, hDevice) 
PKBDKEYINFO pkkiBuffer,; /« pointer to structure for keystrokes — «/ 
PUSHORT pcRecords; /»« pointer to variable for record count «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/« device handle »/ 


The KBD_READCHAR function retrieves one or more character data records 
from the keyboard-input buffer for the screen group of the active process. 


pkkiBuffer Points to the structure that receives the character data records. 
The structure must be at least as large as the size of an individual record multi- 
plied by the requested number of records to be read. The KBDKEYINFO struc- 
ture has the following form: 
typedef struct _KBDKEYINFO { 

UCHAR chChar; 

UCHAR chScan; 

UCHAR fbStatus; 

UCHAR bNisShift; 

USHORT fsState; 


ULONG time; 
} KBDKEYINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pcRecords Points to the variable that contains the number of records to 
be read. When the function returns, it copies the actual number of records 
retrieved to the variable. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. , 


This function copies the records to the buffer pointed to by the pkkiBuffer 
parameter. The variable pointed to by the pcRecords parameter specifies the 
number of records to copy. The function can copy up to 16 characters. 


If the variable pointed to by pcRecords is KBD_.READ_WAIT, the function 
waits for the requested number of keystrokes; it blocks the calling process 
until all records have been read. If the variable is KBD_.READ_NOWAIT, 
the function retrieves any available records (up to the specified number) and 
returns immediately. When the function returns, it copies the actual number of 
records retrieved to the variable. It sets the sign bit to 0 if the input mode is 
ASCII; it sets the sign bit to 1 (0x8000) if the input mode is binary. 


DosOpen, KbdCharIn, KBD_PEEKCHAR 


KBD_SETFGNDSCREENGRP 


USHORT DosDeviOCtl( OL, pusScreenGrp, 0x0055, 0x0004, hDevice) 
PUSHORT pusScreenGrp; /« pointer to structure with screen group «/ 


HFILE hDevice; 


/» device handle xf 


The KBD_SETFGNDSCREENGRP function sets the new foreground screen 
group. When the keyboard switches to the new screen group, it switches to the 
shift state, input buffer, and monitor chain defined for that screen group. 


This function is reserved for the session manager. 
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Parameters pusScreenGrp Points to the SCREENGROUP structure that contains 
the screen-group identifier of the new foreground screen group. The 
SCREENGROUP structure has the following form: 
typedef struct _SCREENGROUP { , 
USHORT idScreenGrp; 


USHORT fTerminate; 
} SCREENGROUP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


‘Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, KBD_SETSESMGRHOTKEY 


KBD_SETFOCUS 


USHORT DosDeviOCti( OL, phkbd, 0x0057, 0x0004, hDevice) 
PHKBD phkbd; /»« pointer to logical keyboard handle «/ 


HFILE hDevice; /« device handle x/ 
The KBD_SETFOCUS function sets the keyboard focus to the specified logical 
keyboard. : 

Parameters phkbd Points to the logical keyboard handle. The handle must have been 


created previously by using the KbdOpen function. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, KbdOpen 


KBD_SETINPUTMODE 


USHORT DosDeviO0Ctl( OL, pbinputMode, 0x0051, 0x0004, hDevice) 
PBYTE pbinputMode; _/« pointer to variable with input mode +/ 
HFILE hADevice; /« device handle , »/ 


The KBD_SETINPUTMODE function sets the input and shift-report modes 
for the keyboard device driver. The input mode defines whether the following 
input keys are processed as keystrokes or as commands: CONTROL+C, 
CONTROL+BREAK, CONTROL+S, CONTROL+P, SCROLL LOCK, PRINTSCREEN. 


The shift-report mode defines whether the shift keys are processed as shift keys 
or as keystrokes. 


Parameters pbInputMode Points to the variable that contains the input mode for the key- 
: board. If the variable is ASCII_MODE, the input mode is ASCII. If the vari- 
able is BINARY_MODE, the input mode is binary. If these values are combined 
with SHIFT_.REPORT_MODE, the function enables the shift-report mode; 
otherwise, the shift-report mode is disabled. 
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Return Value 
Comments 


See Also 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value i is zero if the function is successful or an error value if an error 
occurs. 


The default input mode is ASCII. The keyboard device driver maintains an 
input mode for each screen group. 


DosOpen, KBD_GETINPUTMODE 


KBD_SETINTERIMFLAG 
USHORT DosDevi0Ctl( OL, pfFiags, 0x0052, 0x0004, hDevice) 


PBYTE pfFlags; 
HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


KBD_SETKCB 


/« pointer to variable with flags »/ 
/x device handle s/ 


The KBD_SETINTERIMFLAG function sets the interim character flags. 


pfFlags Points to the variable that contains the interim flags. If the variable is 
0x0020, the program requested conversion. If the variable is 0x0080, the interim 


_ character flag is set. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


The keyboard device driver maintains the interim character flags for each screen 
group and passes the interim character flags (with each character data record) to 
the keyboard monitors. The interim character flags set by this function are not 
the same as the interim character flags in a character data record. 


DosOpen, KBD_GETINTERIMFLAG 


USHORT DosDeviOCtl( OL, phKba, 0x0058, 0x0004, hDevice) 


PHKBD phKbd; 
HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« logical-keyboard handle «/ 
/» device handle s/ 


The KBD_SETKCB function binds the specified bogie keyboard (KCB) to the 
physical keyboard for this session. 


phKbd Points to the handle that identifies the logical keyboard. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. e 


KbdGetFocus 


™@ KBD_SETNLS 
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USHORT DosDeviOCtl(OL, pbCodePage, Ox005C, 0x0004, hDevice) 


PBYTE pbCodePage; 


HFILE hDevice; 


Parameters 


Return Value 
Comment 


See Also 


/« pointer to structure with code-page info «/ 
/»« device handle «/ 


The KBD_SETNLS function installs one of two possible code pages into the 
device driver and updates entry number one or number two of the code-page 
control block. Entry zero is the device-driver resident code page. 


pbCodePage Points to the CODEPAGEINFO structure that specifies the 
translation table and code page to be set. The CODEPAGEINFO structure has 
the following form: 
typedef struct _CODEPAGEINFO { 
PBYTE pbTransTable; 
USHORT idCodePage; 


USHORT idTable; 
} CODEPAGEINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


This function is similar to KBD_SETTRANSTABLE (0x0004 ,0x0050) except it 
updates different entries in the code-page control block. 


DosOpen, KBD_SETTRANSTABLE, KbdSetCustCp 


™ KBD_SETSESMGRHOTKEY 
USHORT DosDevi0Ctl( OL, pbHotKey, 0x0056, 0x0004, hDevice) 


PBYTE pbHotKey; 
HFILE hDevice; 


Parameters 


Return Value 


/« pointer to structure with hot key «/ 
/« device handle «/ 


The KBD_SETSESMGRHOTKEY function sets the session-manager hot keys. 
A new hot key applies to all screen groups. The session manager can define up 
to 16 hot keys. 


pbHotKey Points to the HOTKEY structure that contains the hot-key informa- 
tion. The HOTKEY structure has the following form: 


typedef struct _HOTKEY { 
USHORT fHotKey; 
UCHAR scancodeMake; 
UCHAR scancodeBreak; 
USHORT idHotKey; 

} HOTKEY; 


- For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 
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Comments The KBD_SETSESMGRHOTKEY function is successful only if it is performed 
by the process that initially called the KBD_SETFGNDSCREENGRP function 


NNALEN 
(6x0004, 0x6055). 


A hot key can be specified as a combination of shift flags and scan codes, 
including key combinations such as ALT+ESC. The system detects the hot key 
when the specified scan code is received. If a hot key has already been defined 
for a given hot-key identifier, specitying the identifier again replaces the previous 
definition. 


See Also DosOpen, KBD_GETSESMGRHOTKEY, KBD_SETFGNDSCREENGRP 


KBD_SETSHIFTSTATE 


USHORT DosDeviOCtl( OL, pbShiftState, 0x0053, 0x0004, hDevice) 
PBYTE pbShiftState; /« pointer to structure with shift state «/ 
HFILE hDevice; /« device handle «/ 


The KBD_SETSHIFTSTATE function sets the shift state for the default key- 
board in the current screen group. The shift state identifies whether the SHIFT, 
CONTROL, ALT, INSERT, and SYSREQ keys are up or down and whether the 
SCROLL LOCK, NUMLOCK, CAPSLOCK, and INSERT modes are on. 


Parameters pbShiftState Points to the SHIFTSTATE structure that contains the shift state. 
The SHIFTSTATE structure has the following form: 
typedef struct _SHIFTSTATE { 
USHORT fsState; 


BYTE fbNLS; 
} SHIFTSTATE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments The system puts the shift state into the character data record built for each 


incoming keystroke; the shift state then can be used to interpret the meaning of 
keystrokes. The function sets the shift state to the specified state regardless of 
the state of the actual keys. The shift remains as set until the user presses or 
releases the corresponding key. 


The keyboard device driver maintains a shift state for each screen group. 


See Also ’ DosOpen, KBD_GETSHIFTSTATE 


KBD _SETTRANSTABLE 


USHORT DosDeviOCtI( OL, pbTransTable, 0x0050, 0x0004, hDevice) 
PBYTE pbTransTable; /« pointer to translation table »/ 
HFILE hDevice; /« device handle x/ 


The KBD_SETTRANSTABLE function passes a new translation table to the 
keyboard translation function. The new table, which overlays the current table, 
translates subsequent keystrokes. 
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Parameters pbTransTable Points to the translation table. 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

Comments The default translation table is U.S. English. 

See Also DosOpen 


KBD_SETTYPAMATICRATE 


USHORT DosDeviOCtl( OL, pusRateDelay, 0x0054, 0x0004, hDevice) 
PUSHORT pusRateDelay; /« structure with typamatic rate and delay «/ 


HFILE hDevice; /« device handle »/ 
The KBD_SETTYPAMATICRATE function sets the keyboard typamatic rate 
and delay. 

Parameters pusRateDelay Points to the RATEDELAY structure that contains the 


typamatic rate and delay. The RATEDELAY structure has the following form: 


typedef struct _RATEDELAY { 
USHORT delay; 
USHORT rate; 

} RATEDELAY; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, GETTYPAMATICRATE 

KBD_XLATESCAN 

USHORT DosDevlOCtl( pkbx/, pidCodePage, 0x0079, 0x0004, hDevice) 

PKBDXLATE pkbx/; /« pointer to structure for scan code «/ 

PBYTE pidCodePage; /« pointer to code page for translation «/ 

HFILE hDevice; /» device handle »/ 


The KBD_XLATESCAN function translates a scan code in a character data 
record to an ASCII character. 


Parameters pkbxl Points to the KBDTRANS structure that contains the scan code to 
translate. It also receives the character value when the function returns. The 
KBDTRANS structure has the following form: 
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typedef struct _KBDTRANS { 
UCHAR ehChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNisShift; 
USHORT fsState; 
ULONG time; 
USHORT. fsDD; 
USHORT fsXlate; 
USHORT fsShift; 
USHORT sZero; 

} KBDTRANS; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pidCodePage Points to a code-page identifier that specifies which code page 
to use for the translation. The code-page identifier can be one of the following 


values: 
Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian 
865 Nordic 


hDevice Identifies the keyboard that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments You may specify a code page to use for translation. Otherwise, the code page of 


the active keyboard is used. On entry, the KBDTRANS structure specifies the 
code page to use for translation. 


See Also KbdXlate 


MON_REGISTERMONITOR 
USHORT DosDevlOCtl( pusinfo, pb>Command, 0x0040, 0x000A, hDevice) 


PUSHORT pusinfo; /« pointer to structure with monitor-register info »/ 
PBYTE pbCommand; /» pointer to command »/ 
HFILE hDevice; /« device handle »/ 
The MON_REGISTERMONITOR function registers a monitor. 
Parameters pusInfo Points to the MONITORPOSITION structure that contains the 


monitor-registration information. The MONITORPOSITION structure has the 
following form: 


typedef struct _MONITORPOSITION { 
USHORT position; 
USHORT index; 
PBYTE pbinBuf; 
USHORT offset; 
} MONITORPOSITION; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


Return Value 


See Also 
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pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the device that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosMonRead, DosMonReg, DosMonWrite, DosOpen 


MOU_ALLOWPTRDRAW 


USHORT DosDeviOCti( OL, OL, 0x0050, 0x0007, hDevice) 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« device handle «/ 


The MOU_ALLOWPTRDRAW function notifies the mouse device driver that 
the screen group has been switched and that the pointer can now be drawn. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen 


MOU_DRAWPTR 


USHORT DosDeviOCti( OL, OL, 0x0057, 0x0007, hDevice) 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/x device handle «/ 


The MOU_DRAWPTR function removes the current exclusion rectangle, allow- 
ing the pointer to be drawn anywhere on the screen. If an exclusion rectangle 
has been declared for the screen group, that rectangle is released and the pointer 
position is checked. If the pointer was in the released rectangle, it is drawn. If 
the pointer was not in the released rectangle, the pointer-draw operation occurs. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen 
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— MOU_GETBUTTONCOUNT 


USHORT DosDeviOCtI( pusCount, OL, 0x0060, 0x0007, hDevice) 


PUSHORT pusCount; /« pointer to variable for button count «/ 
HFILE hDevice; /« device handle x/ 


The MOU_GETBUTTONCOUNT function retrieves a count of the number of 
mouse buttons. 
Parameters pusCount Points to the variable that receives the count mouse buttons. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen 


mM MOU_GETEVENTMASK 


USHORT DosDeviOCtl( pfEvents, OL, 0x0065, 0x0007, hDevice) 
PUSHORT pfEvents; /« pointer to variable for event mask «/ 
HFILE hDevice; /« device handle s/ 


The MOU_GETEVENTMASK function retrieves the event mask of the current 
pointing device. 


Parameters pfEvents Points to the variable that receives the event mask. This variable can 
be a combination of the following values: 

Value Meaning 
MOUSE_MOTION Motion; no buttons pressed. 
MOUSE_MOTION_WITH_BN1_DOWN Motion with button 1 pressed. 
MOUSE_BN1_DOWN Button 1 pressed. 
MOUSE_MOTION_WITH_BN2_DOWN Motion with button 2 pressed. 
MOUSE_BN2_DOWN Button 2 pressed. 
MOUSE_MOTION_WITH_BN3_DOWN Motion with button 3 pressed. 
MOUSE_BN3_DOWN Button 3 pressed. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, MOU_SETEVENTMASK 
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mM MOU_GETHOTKEYBUTTON 


USHORT DosDeviOCtl( pfHotKey, OL, 0x0069, 0x0007, hDevice) 
PUSHORT pfHotKey; _—/= pointer to variable for hot key +/ 
HFILE hDevice; /« device handle »/ 


The MOU_GETHOTKEYBUTTON function retrieves the mouse-button 
equivalent for the system hot key. 


Parameters pfHotKey Points to the variable that receives the hot key. This variable can be 
one or more of the following values: 
Value Meaning 
MHK_NO_HOTKEY No system hot key used. 
MHK_BUTTONI1 Button 1 is system hot key. 
MHK_BUTTON2 Button 2 is system hot key. 
MHK_BUTTON3 Button 3 is system hot key. 


If 0x0001 is specified, no system hot-key support is provided. If multiple values 
are given (excluding 0x0001) the system hot key requires that the indicated but- 
tons be pressed simultaneously. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, MOU_SETHOTKEYBUTTON 


—@ MOU_GETMICKEYCOUNT 


USHORT DosDeviOCtl( pcMickeys, OL, 0x0061, 0x0007, hDevice) 
PUSHORT pcMickeys; /« pointer to variable for mickeys »«/ 
HFILE hDevice; /« device handle »/ 


The MOU_GETMICKEYCOUNT function retrieves the count of mickeys per 
centimeter for a given pointing device. 


Parameters pcMickeys Points to the variable that receives the number of mickeys per 
centimeter. The number can be any value from 0 through 32,767. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen 
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MOU_GETMOUSTATUS 


USHORT DosDeviOCti( pfStatus, OL, 0x0062, 0x0007, hDevice) 
PUSHORT pfStatus; /» pointer to variable for status flags «/ 
HFILE hDevice; /« device handle x/ 


The MOU_GETMOUSTATUS function retrieves the current status flags of the 
mouse device driver. 


Parameters pfStatus Points to the variable that receives the status flags. This variable can 
be a combination of the following values: 
Value Meaning 
MOUSE_QUEUVEBUSY Event queue is busy with I/O. 
MOUSE_BLOCKREAD Block read is in progress. 
MOUSE_FLUSH Flush is in progress. 


MOUSE_UNSUPPORTED_MODE  Pointer-draw routine is disabled (device 
in unsupported mode). 


MOUSE_DISABLED Interrupt-level pointer-draw routine is 
not called. 

MOUSE_MICKEYS Mouse data is returned in mickeys (not 
pels). 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 
Return Value — The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, MOU_LSETMOUSTATUS 


MOU_GETPTRPOS 
USHORT DosDeviOCtI( pp/Position, OL, 0x0067, 0x0007, hDevice) 
PPTRLOC ppiPosition; /» pointer to structure for position «/ 


HFILE hDevice; /« device handie __ »/ 
The MOU_GETPTRPOS function retrieves the position of the current screen’s 
pointer. 

Parameters pplPosition Points to the PTRLOC structure that receives the new pointer 


position. The PTRLOC structure has the following form: 


typedef struct _PTRLOC { 
USHORT row; 
USHORT col; 

} PTRLOC; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


Return Value 


Comments 


See Also 
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The return value is zero if the function is successful or an error value if an error 
occurs. 


The coordinate values depend on the display mode. If the display is in text 
mode, character-position values are used. If the display is in graphics mode, 
pel values are used. 


DosOpen, MOU_SETPTRPOS 


MOU_GETPTRSHAPE 


USHORT DosDevliOCtl( pbBuffer, ppsShape, 0x0068, 0x0007, hDevice) 


PBYTE pbBuffer; 


/« pointer to buffer for pointer masks »/ 


PPTRSHAPE ppsShape; /« pointer to structure for shape information «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


_ /« device handle »/ 
The MOU_GETPTRSHAPE function retrieves the current pointer shape. 


pbBuffer Points to the buffer that receives the pointer shape. The image for- 
mat depends on the mode of the display. For currently supported modes, the 
buffer always consists of the AND image data followed by the XOR image data. 
The buffer always describes one display plane. 


ppsShape Points to the PTRSHAPE structure that receives the pointer infor- 
mation and shape. The PTRSHAPE structure has the following form: 
typedef struct _PTRSHAPE { 
USHORT cb; 
USHORT col; 
USHORT row; 
USHORT colHot; 
USHORT rowHot; 
} PTRSHAPE; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. : 


The function exits in a normal state if the input pointer-image buffer is large 
enough to store the pointer image. The current pointer information is returned 
in the pointer-data record, and the pointer-image data is copied into the data- 
packet buffer. 


An “invalid buffer size” error occurs if the input pointer-image buffer is smaller 
than the amount of storage necessary for copying the data. The buffer length 
returned will be minimum value. 


The parameter values are in the same mode as the current screen-group display 
mode. For text mode, these are character values; for graphics mode, these are 
pel values. 


On input, the only field in the pointer-definition record used by the mouse 
device driver is the length of the pointer-image buffer. 


DosOpen, MOU_SETPTRSHAPE 
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MOU_GETQUESTATUS 


USHORT DosDeviOCtl( pmaqiSta tus, OL, 0x0064, 0x0007, hDevice) 
PMOUQUEINFO pmdiStatus; /« pointer to structure for queue status «/ 
HFILE hDevice; /« device handle x/ 


The MOU_GETQUESTATUS function retrieves the number of elements in the 
event queue and the maximum number of elements allowed in an event queue. 


Parameters pmqdiStatus Points to the MOUQUEINFO structure that receives the queue 
status. The MOUQUEINFO structure has the following form: 
typedef struct _MOUQUEINFO { 
USHORT cEvents; 


USHORT cmaxEvents; 
} MOUQUEINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function, 
Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen 


MOU_GETSCALEFACTORS 


USHORT DosDevlOCtl(psfFactors, OL, 0x0066, 0x0007, hDevice) 
PSCALEFACT psfFactors; /« pointer to structure for scaling factors »/ 
HFILE hDevice; /« device handle »/ 


The MOU_GETSCALEFACTORS function retrieves the scaling factors of the 
current pointing device. Scaling factors are the ratio values that determine how 
much relative movement is necessary before the mouse device driver reports a 
pointing-device event. In graphics mode, this ratio is given in mickeys-per-pel. In 
text mode, this ratio is given in mickeys-per-character. The default values are 

_ one mickey-per-row and one mickey-per-column. 


Parameters psfFactors Points to the SCALEFACT structure that receives the scaling fac- 
tors. The SCALEFACT structure has the following form: 
typedef struct _SCALEFACT { 
USHORT rowScale; 


USHORT colScale; 
} SCALEFACT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


_hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, MOU_SETSCALEFACTORS 
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M@ MOU_READEVENTQUE 


USHORT DosDevlOCtl( pmeiEvent, pfWait, 0x0063, 0x0007, hDevice) 
PMOUEVENTINFO pmeiEvent; /« pointer to structure for event information »/ 


PUSHORT pfWait; 
HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to wait/no-wait flag «/ 
/» device handle »/ 


The MOU_LREADEVENTOQUE function reads the event queue for the pointing 
device. 


pmeiEvent Points to the MOUEVENTINFO structure that receives event- 
queue information. The MOUEVENTINFO structure has the following form: 
typedef struct _MOUEVENTINFO { 

USHORT fs; 

ULONG Time; 

USHORT row; 


USHORT col; 
} MOUEVENTINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pfWait Points to the variable that specifies how to read from the queue if no 
event is available. If the variable is WAIT, the function returns immediately 
without an event. If the variable is NOWAIT, the function waits until an event is 
available. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, MouReadEventQue 


™ MOU_REMOVEPTR 


USHORT DosDeviOCtl( OL, pnprBuffer, Ox0058, 0x0007, hDevice) 
PNOPTRRECT pnprBuffer; /« points to structure with exclusion rectangle «/ 


HFILE hDevice; 


Parameters | 


/« device handle x/ 


The MOU_REMOVEPTR function specifies the exclusion rectangle to be used 
by the device driver. The exclusion rectangle specifies an area on the screen 
where the pointer-draw routine cannot draw the pointer. 


pnprBuffer Points to the NOPTRRECT structure that contains the dimensions 
of the exclusion rectangle. The NOPTRRECT structure has the following form: 
typedef struct _NOPTRRECT { 

USHORT row; 

USHORT col; 

USHORT cRow; 


USHORT cCol; 
} NOPTRRECT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 
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Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments The pointer is not drawn in the exclusion rectangle until a different area is speci- 


fied by another call of this function. 


If the exclusion rectangle is defined as the entire screen, pointer-draw operations 
are disabled for the entire screen group. 


See Also DosOpen 


MOU_SCREENSWITCH 


USHORT DosDeviOCtl( OL, pbNotify, 0x0052, 0x0007, hDevice) 
PBYTE pbNotify; /« pointer to structure with screen group «/ 
HFILE hDevice; /« device handle «/ 


The MOU_SCREENSWITCH function notifies the mouse device driver that 

the screen group is about to be switched, and then sets a system pointer-draw 
enable/disable flag. Any pointer drawing is locked until the flag is cleared by 

using the MOU_LALLOWPTRDRAW function (0x0007, 0x0050).. 


Parameters pbNotify Points to the SCREENGROUP structure that contains the notifi- 


cation type and screen-group identifier. The SCREENGROUP structure has the 
following form: 


typedef struct _SCREENGROUP { 
USHORT idScreenGrp; 
USHORT fTerminate; 

} SCREENGROUP; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen 


MOU_SETEVENTMASK 


USHORT DosDeviOCtl( OL, pfEvent, 0x0054, 0x0007, hDevice) 
PUSHORT pfEvent; /» pointer to variable for event mask «/ 
HFILE hDevice; /« device handle s/ 


The MOU_SETEVENTMASK function sets the event mask of the pointing 
device. 


Parameters 


Return Value 


See Also 
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pfEvent Points to the variable that contains the event mask. This variable can 
be a combination of the following values: 


Value Meaning 

MOUSE_MOTION Motion; no buttons pressed. 
MOUSE_MOTION_WITH_BN1_DOWN Motion with button 1 pressed. 
MOUSE_BN1_DOWN Button 1 pressed. 
MOUSE_MOTION_WITH_BN2_DOWN Motion with button 2 pressed. 
MOUSE_BN2_DOWN Button 2 pressed. 
MOUSE_MOTION_WITH_BN3_LDOWN Motion with button 3 pressed. 
MOUSE_BN3_DOWN Button 3 pressed. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, MOU_GETEVENTMASK 


* 


MOU_SETHOTKEYBUTTON 


USHORT DosDevlOCtl( OL, pfHotKey, 0x0055, 0x0007, hDevice) 


PUSHORT pfHotKey; 


HFILE hDevice; 


Parameters 


Return Value 


/« pointer to variable with hot key «/ 
/» device handle »/ 


The MOU_SETHOTKEYBUTTON function sets the mouse-button equivalent 
for the system hot key. 


pfHotKey Points to the variable that specifies the hot key. This variable can 
be a combination of the following values: 


Value Meaning 
MHK_NO_HOTKEY No system hot key used. 
MHK_BUTTON1 Button 1 is system hot key. 
MHK_BUTTON2 Button 2 is system hot key. 
MHK_BUTTON3 Button 3 is system hot key. 


If 0x0001 is specified, no system hot-key support is provided. If multiple values 
are given (excluding 0x0001), the system hot key requires that the indicated but- 
tons be pressed simultaneously. 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 
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Comments This function can be called only by the process that initially issues it and should 
be used only by the command shell. 
See Also DosOpen, MOU_GETHOTKEYBUTTON 


MOU_SETMOUSTATUS 


USHORT DosDeviOCti( OL, pfStatus, 0x005C, 0x0007, hDevice) 
PUSHORT pfStatus; /» pointer to variable with status «/ 
HFILE hDevice; /« device handle x/ 


The MOU_SETMOUSTATUS function sets a subset of the current mouse 
device-driver status flags. 


Parameters pfStatus Points to the variable that contains the status flags for the pointing 
device. If the variable is MOUSE_DISABLED, the interrupt-level pointer-draw 
routine is not called. If the variable is MOUSE_MICKEYS, mouse data is 
returned in mickeys (not pels). 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, MOU_GETMOUSTATUS 


MOU_SETPROTDRAWADDRESS 


USHORT DosDevlOCtl( OL, pbFunction, 0x005A, 0x0007, hDevice) 
PBYTE pbFunction; /« pointer to structure with drawing function »/ 
HFILE hDevice; /« device handle »/ 


The MOU_SETPROTDRAWADDRESS function notifies the mouse device 
driver of the address of a protected-mode pointer-draw function. This function 
is valid for protected mode only. 


Parameters pbFunction Points to the PTRDRAWFUNCTION structure that contains the 


address of the pointer-draw function. The PTRDRAWFUNCTION structure has 
the following form: 


typedef struct _PTRDRAWFUNCTION { 
PEN pfnDraw; 
PCH pcohDataSseg; 

} PTRDRAWFUNCTION; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. . 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


Comments 


See Also 


MOU_SETPTRPOS = 305 


The pointer-draw routine is an installed, pseudo-character device driver. The 
mouse handler must do the following: 

™@ §©Open the pointer-draw device driver. 

™ Query the pointer-draw device driver for the address of its entry point. 


@ Pass the resulting address of the pointer-draw entry point to the mouse 
device driver that uses this function. 


DosOpen, MOU_LSETREALDRAWADDRESS 


MOU_SETPTRPOS 


USHORT DosDeviOCti( OL, pp/Position, 0x0059, 0x0007, hDevice) 
PPTRLOC ppiPosition; /« pointer to structure with pointer position «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/x device handle x/ 


The MOU_SETPTRPOS function sets a new screen position for the pointer | 
image. 


pplPosition Points to the PTRLOC structure that contains the new position 
for the pointer. The PTRLOC structure has the following form: 
typedef struct _PTRLOC { 

USHORT row; 


USHORT col; 
} PTRLOC; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 
function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


The coordinate values depend on the display mode. If the display is in text 
mode, character-position values are used. If the display is in graphics mode, 
pel values are used. 


This function has no effect on the current exclusion-rectangle definitions. If a 
pointer image is already defined for the screen group, it is replaced by the new 
pointer image. 


If the pointer image is directed into an existing exclusion rectangle, it remains 
hidden (invisible) until sufficient movement places the pointer outside the exclu- 
sion rectangle or until the exclusion rectangle is released. 


DosOpen, MOU_GETPTRPOS 
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™ MOU_SETPTRSHAPE | 


USHORT DosDeviOCtl( pbBuffer, ppsShape, 0x0056, 0x0007, hDevice) 


PBYTE pbBuffer; 


peace 


/« pointer to structure with shape masks x/ 


PPTRSHAPE ppsShape; /« pointer to structure with shape information «/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also | 


/» device handle »/ 
The MOU_SETPTRSHAPE function sets the pointer shape. 


pbBuffer Points to the buffer that contains the pointer image. The image for- 
mat depends on the mode of the display. For currently supported modes, the _ 
buffer always consists of the AND image data, followed by the XOR image data. 
The buffer always describes one display plane. 


ppsShape Points to the PTRSHAPE structure that receives the pointer infor- 
mation and shape. The PTRSHAPE structure has the following form: 


typedef struct _PTRSHAPE { 
USHORT cb; 
USHORT col; 
USHORT row; 
USHORT colHot; 
USHORT rowHot; 
} PTRSHAPE ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


The parameter values must be in the same mode as the current screen-group 
display mode. For text mode, these must be character values; for graphics 
mode, these must be pel values. 


DosOpen, MOU_GETPTRSHAPE 


™ MOU_SETREALDRAWADDRESS | 
USHORT DosDeviOCti( OL, pbFunction, 0x005B, 0x0007, hDevice) 


PBYTE pbFunction; 


HFILE hDevice; 


Parameters 


/x pointer to structure with function «/ 
/x device handle »/ 


The MOU_SETREALDRAWADDRESS function notifies the real-mode mouse 
device driver of the entry point of a real-mode pointer-draw routine. This func- 
tion is intended for use by the session manager at the end of system initialization 
and is valid for real mode only. 


pbFunction Points to the PTRDRAWFUNCTION structure that contains the 
address of the pointer-draw function. The PPRDRAWFUNCTION structure has 
the following form: 
typedef struct _PTRDRAWFUNCTION { 

PEN pfnDraw; 


PCH pchDataSeg; 
} PTRDRAWFUNCTION; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
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hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, MOU_SETPROTDRAWADDRESS 


MOU_SETSCALEFACTORS 


USHORT DosDeviOCtl( OL, psfFactors, 0x0053, 0x0007, hDevice) 
PSCALEFACT psfFactors; /« pointer to structure with factors «/ 
HFILE hDevice; /x device handle »/ 


The MOU_SETSCALEFACTORS function reassigns the scaling factors of the 
current pointing device. Scaling factors are ratio values that determine how 
much relative movement is necessary before the mouse device driver reports a 
pointing-device event. In graphics mode, the ratio is given in mickeys-per-pel. In 
text mode, the ratio is given in mickeys-per-character. The default ratio values 
are one mickey-per-row and one mickey-per-column. 


Parameters psfFactors Points to the SCALEFACT structure that contains the scale fac- 
tors. The SCALEFACT structure has the following form: 


typedef struct _SCALEFACT { 
USHORT rowScale; 
USHORT colScale; 

} SCALEFACT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosOpen, MOU_GETSCALEFACTORS 


MOU_UPDATEDISPLAYMODE 


USHORT DosDeviOCtl( OL, pviomi, 0x0051, 0x0007, hDevice) 
PVIOMODEINFO pviomi; /« pointer to structure with screen mode »/ 
HFILE hDevice; /« device handle »/ 


The MOU_UPDATEDISPLAYMODE function notifies the mouse device driver 
that the display mode has been modified. 


Parameters pviomi Points to the VIOMODEINFO structure that contains the display- 
mode information. The VIOMODEINFO structure has the following form: 
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typedef struct _VIOMODEINFO { 
USHORT cb; 
UCHAR fbType; 
UCHAR color; 
USHORT col; 
USHORT. row; 
USHORT hres; 
USHORT vres; 
UCHAR fmt_ID; 
UCHAR attrib; 

} VIOMODEINEFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the pointing device that receives the device-control func- 
tion. The handle must have been created previously by using the DosOpen 


function. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

Comments When the video I/O subsystem or registered video I/O subsystem sets the 


display mode, it must notify the mouse device driver prior to switching display 
modes, in order to synchronize the mouse device driver’s functions that update 
the pointer. 


See Also DosOpen, VioSetMode 


PDSK_GETPHYSDEVICEPARAMS . 
USHORT DosDevlOCti( pbBiock, pbCommand, 0x0063, 0x0009, hDevice) 


PBYTE pbBlock; /x pointer to structure for device parameters «/ 
PBYTE pbCommand; /« pointer to variable with command »/ 
HFILE hDevice; /« device handle x/ 


The PDSK_GETPHYSDEVICEPARAMS function retrieves the device parame- 
ters for a physical device. The retrieved parameters apply to the entire physical 
disk. ; 


Parameters pbBlock Points to the DEVICEPARAMETERBLOCK structure that receives 
the device parameters. The DEVICEPARAMETERBLOCKX structure has the fol- 
lowing form: . 


typedef struct _DEVICEPARAMETERBLOCK { 
USHORT reservedl; 
USHORT cCylinders; 
USHORT cHeads; : 
USHORT cSectorsPerTrack; 
USHORT reserved2; 
USHORT reserved3; 
USHORT reserved4; 
USHORT reservedS; 
} DEVICEPARAMETERBLOCK ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


PDSK_READPHYSTRACK 309 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the physical device that receives the device-control func- 
tion. The handle must have been created previously by using the DosPhysical- 
Disk function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosPhysicalDisk 

PDSK_LOCKPHYSDRIVE 


USHORT DosDevi0Ctl( OL, pb>Command, 0x0000, 0x0009, hDevice) 
PBYTE pbCommand; /x pointer to variable with command «/ 
HFILE hDevice; /« device handle »/ 


The PDSK_LOCKPHYSDRIVE function locks the physical drive and any of its 
associated logical units. 


Parameters pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk-drive device that receives the device-control func- 
tion. The handle must have been created previously by using the DosPhysical- 
Disk function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

See Also DosPhysicalDisk, PDSK_UNLOCKPHYSDRIVE 

PDSK_READPHYSTRACK 

USHORT DosDeviOCtl( pbBuffer, pbbCommand, 0x0064, 0x0009, hDevice) 

PBYTE pbBuffer; /» pointer to structure for data »/ 

PBYTE pbCommand; /x pointer to structure with command »/ 

HFILE hDevice; /« device handle »/ 


The PDSK_READPHYSTRACK function reads from a physical track on the 
device specified in the request. 


Parameters pbBuffer Points to the buffer that receives the data to be read. 


pbCommand Points to the TRACKLAYOUT structure that contains informa- 
tion about the read operation. The TRACKLAYOUT structure has the following 
form: 
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Return Value 


Comments 


See Also 


typedef struct _TRACKLAYOUT { 
BYTE bCommand; 


USHORT head; 
USHORT cylinder; 


weawee pe 0 5 05 — 7 


USHORT firstSector; 
USHORT cSectors; 
struct { 
USHORT sectorNumber ; 
USHORT sectorSize; 
} TrackTable[1]; 
} TRACKLAYOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosPhysicalDisk func- 
tion. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


This function is similar to the DSK_READTRACK function (0x0008, 0x0064) 
except that I/O is offset from the beginning of the physical drive instead of from 
the unit number. 


The track table passed in the function determines the sector number, which is 
passed to the disk controller. When the sectors are odd-numbered or noncon- 
secutive, the request is broken into an appropriate number of single-sector 
operations, and one sector at a time is read. 


The device driver will not correctly read sectors of sizes other than 512 bytes if 
doing so would generate a direct-memory-access (DMA) violation error. 


DosPhysicalDisk, DSK_WRITETRACK, PDSK_VERIFYPHYSTRACK, 
PDSK_WRITEPHYSTRACK 


PDSK_UNLOCKPHYSDRIVE 


USHORT DosDeviOCtl( OL, pbCommand, 0x0001, 0x0009, hDevice) 


PBYTE pbCommanda: 


HFILE hDevice; 


Parameters 


Return Value 


See Also 


/« pointer to variable with command «/ 
/x device handle »/ 


The PDSK_UNLOCKPHYSDRIVE function unlocks the physical disk drive and 
any of its associated logical units and also affects the logical units on the physical 
disk drive. 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosPhysicalDisk func- 
tion. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


DosOpen, DosPhysicalDisk, PDSK_.LOCKPHYSDRIVE 
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= PDSK_VERIFYPHYSTRACK 


USHORT DosDeviOCtl( OL, pbCommand, 0x0065, 0x0009, hDevice) 
PBYTE pbCommand; /« pointer to structure with verification data «/ 
HFILE hDevice; /« device handle »/ 


The PDSK_VERIFYPHYSTRACK function verifies I/O on a physical track on 
the device specified in the request. 


Parameters pbCommand Points to the TRACKLAYOUT structure that contains informa- 
tion about the verify operation. The TRACKLAYOUT structure has the follow- 
ing form: 


typedef struct _TRACKLAYOUT { 
BYTE bCommand; 
USHORT head; 
USHORT cylinder ; 
USHORT firstSector; 
USHORT cSectors; 
struct { 
USHORT sectorNumber; 
USHORT sectorSize; 
} TrackTable[1]; 
} TRACKLAYOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the physical device that receives the device-control func- 
tion. The handle must have been created previously by using the DosPhysical- 
Disk function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
Comments This function is similar to the DSK_VERIFYTRACK function (0x0008, 0x0065) 


except that I/O is offset from the beginning of the physical drive instead of from 
the unit number. 


The track-layout table passed in the function determines the sector number, 
which is passed to the disk controller. When the sectors are odd-numbered or 
nonconsecutive, the request is broken into an appropriate number of single- 
sector operations, and one sector at a time is verified. 


See Also DosPhysicalDisk, DSK_VERIFYTRACK, PDSK_READPHYSTRACK, 
PDSK_WRITEPHYSTRACK 


@ PDSK_WRITEPHYSTRACK | 
USHORT DosDeviOCtl( pbBuffer, pbbCommand, 0x0044, 0x0009, hDevice) 


PBYTE pbBuffer; /» pointer to buffer with data »/ 
PBYTE pbCommand; /« pointer to structure with command «/ 
HFILE hDevice; /« device handle »/ 


The PDSK_WRITEPHYSTRACK function writes to a physical track on the 
device specified in the request. 


Parameters pbBuffer Points to the buffer that contains the data to be written. 


pbCommand Points to the TRACKLAYOUT structure that contains informa- 
tion about the write operation. The TRACKLAYOUT structure has the following 
form: 
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typedef struct _TRACKLAYOUT { 
BYTE bCommand; 
USHORT head; 


ISTIADT wmerlinaAaayr- 
VOMVNL Vy 4 esis ; 


USHORT firstSector; 
USHORT cSectors; 
struct { 
USHORT sectorNumber; 
USHORT sectorSize; 
} TrackTable[1]; 
} TRACKLAYOUT; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


hDevice Identifies the disk drive that receives the device-control function. The 
handle must have been created previously by using the DosPhysicalDisk func- 


tion. 

Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 

Comments This function is similar to the DSK_WRITETRACK function (0x0008, 0x0044) 


except that I/O is offset from the beginning of the physical drive instead of from 
the unit number. 


The track-layout table passed in this function determines the sector number, 
which is passed to the disk controller. When the sectors are odd-numbered or 
nonconsecutive, the request is broken into an appropriate number of single- 
sector operations, and one sector at a time is written. 


See Also DosPhysicalDisk, DSK_WRITETRACK, PDSK_READPHYSTRACK, 
PDSK_VERIFYPHYSTRACK 

PRT_ACTIVATEFONT 

USHORT DosDeviOCtl( pbFontinfo, pbCommand, 0x0048, 0x0005, hDevice) 

PBYTE pbFontinfo; /x pointer to structure for fontinfo —«/ 

PBYTE pbCommand; /« pointer to byte with command info «/ 

HFILE hDevice; /« device handle »/ 


The PRT_.ACTIVATEFONT function activates a font for printing. 
Parameters pbFontInfo Points to a FONTINFO structure that specifies the font to 
activate. ‘The FONTINFO structure has the following form: 
typedef struct _FONTINFO { 
USHORT idCodePage; 


USHORT idFont; 
} FONTINFO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
pbCommand Points to a reserved 8-bit value. The value must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also PRT_QUERYACTIVEFONT 


PRT_GETINFINITERETRY 313 


@ PRT_GETFRAMECTL 
USHORT DosDeviOCtl( pbFrameCti, pbCommand, 0x0062, 0x0005, hDevice) 


PBYTE pbFrameCti; /» pointer to structure for frame settings »/ 

PBYTE pbCommand; /« pointer to variable with command _ «/ 

HFILE hDevice; /s device handle «/ 
The PRT_.GETFRAMECTL function retrieves frame-control information for a 
printer. 

Parameters pbFrameCtl Points to the FRAME structure that receives the frame-control 


information. The FRAME structure has the following form: 


typedef struct _FRAME { 
BYTE bCharsPerLine; 
BYTE bLinesPerInch; 
} FRAME; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also DosOpen, PRT_SETFRAMECTL 


@ PRT_GETINFINITERETRY 
USHORT DosDevlOCtl( pfRetry, pb>Command, 0x0064, 0x0005, hDevice) 


PBYTE pfRetry; /« pointer to variable for retry flag «/ 
PBYTE pbCommand; /« pointer to variable with command «/ 
HFILE hDevice; /« device handle »/ 
The PRT_GETINFINITERETRY function retrieves an infinite retry setting for a 
printer. . 
Parameters pfRetry Points to the variable that receives the infinite retry setting. The vari- 


. able is FALSE if infinite retry is disabled or TRUE if retry is enabled. 


pbCommand _ Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, PRT_SETINFINITERETRY 


314. PRT_GETPRINTERSTATUS 


@ PRT_GETPRINTERSTATUS 
USHORT DosDeviOCt( pfStatus, pbCommand, 0x0066, 0x0005, hDevice) 


PBYTE pfStatus; /« pointer to printer status flag +/ 
PBYTE pbCommand; /« pointer to variable with command «/ 
HFILE hDevice; /« device handle s/ 


The PRT_GETPRINTERSTATUS function retrieves the status of a printer. 


Parameters pfStatus Points to the variable that receives the printer status. This variable 
. can be a combination of the following values: 

Value : Meaning 
PRINTER_TIMEOUT Time-out occurred. 
PRINTER_IO_ERROR I/O error occurred. 
PRINTER_SELECTED Printer selected. 
PRINTER_OUT_OF_PAPER Printer out of paper. 
PRINTER_ACKNOWLEDGED Printer acknowledged. 
PRINTER_NOT_BUSY Printer not busy. 


pbCommand _ Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 


occurs, 
See Also DosOpen 


mM PRT_INITPRINTER 


USHORT DosDeviOCtl( OL, pbCommand, 0x0046, 0x0005, hDevice) 
PBYTE pbCommand; _—_/« command value +/ 
HFILE hDevice; /x device handle — «/ 


The PRT_INITPRINTER function initializes a printer. 


Parameters pbCommand Points to the variable that contains a reserved value. The value 
. must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
, occurs. — 


See Also DosOpen 


PRT_SETFRAMECTL 315 


@ PRT_QUERYACTIVEFONT 
USHORT DosDeviOCtl( pbFontinfo, pbCommand, 0x0069, 0x0005, hDevice) 


PBYTE pbFontinfo; /« pointer to structure for font information. «/ 
PBYTE pbCommand; / pointer to byte with command information «/ 
HFILE hDevice; /x device handle x/ 


The PRT_QUERYACTIVEFONT function determines which code page and 
font are currently active. 
Parameters pbFontInfo Points to a FONTINFO structure that specifies the active font. 
The FONTINFO structure has the following form: 
typedef struct _FONTINFO { 
USHORT idCodePage; 


USHORT idFont; 
} FONTINEO; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 
pbCommand Points to a reserved 8-bit value. The value must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 
See Also PRT_ACTIVATEFONT 


@ PRT_SETFRAMECTL 
USHORT DosDevlOCtI( pbFrameCt!, pbCommand, 0x0042, 0x0005, hDevice) 


PBYTE pbFrameCtl; /« pointer to structure with frame settings «/ 

PBYTE pbCommand; __ /+ pointer to variable with command »/ 

HFILE hDevice; /« device handle »/ 
The PRT_SETFRAMECTL function sets the frame-control information for a 
printer. 

Parameters pbFrameCtl Points to the FRAME structure that contains the frame-control 


information. The FRAME structure has the following form: 
typedef struct _FRAME { 
BYTE bCharsPerLine; 


BYTE bLinesPer Inch; 
} FRAME ; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function i is successful or an error value if an error 
occurs. 


See Also DosOpen, PRT_GETFRAMECTL 


316 PRT_SETINFINITERETRY 


H PRT_SETINFINITERETRY 
USHORT DosDeviOCtl( pfRetry, pbCommand, 0x0044, 0x0005, hDevice) 


PBYTE pfRetry; _ /« pointer to retry flag af 
PBYTE pbCommand; ___/ pointer to variable with command «/ 
HFILE hDevice; — /« device handle »/ 


The PRT_SETINFINITERETRY function sets infinite retry for a printer. 


Parameters pfRetry Points to the variable that specifies whether to enable infinite retry. If 
the variable is FALSE, the function disables infinite retry. If the variable i is 
TRUE, the function enables infinite retry. 


pbCommand Points to the variable that contains a reserved value. The value 
must be zero. 


hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
. occurs. 
See Also DosOpen, PRT_ GETINFINITERETRY 


@ PRT_VERIFYFONT 
USHORT DosDeviOCtl(pbFontinfo, pbCommand, 0x006A, 0x0005, hDevice) 


PBYTE pbFontinfo; © /s points to structure for font info —«/ 
PBYTE pbCommand; /« points to byte with command info «/ 
HFILE hDevice; /» device handle »/ 


The PRT_VERIFYFONT function verifies that a particular code page and font 
are available for the specified printer. 


Parameters pbFontInfo Points to the FONTINFO structure that receives information for 
the available font. The FONTINFO structure has the following form: 
typedef struct _FONTINFO { — 
USHORT idCodePage; 
USHORT idFont; 
} FONTINEO; © 
For a full description, see Chapter 4, “Types, Macros, Structures.” 
pbCommand Points to a reserved 8-bit value. The value must be zero. 
hDevice Identifies the printer that receives the device-control function. The 
handle must have been created previously by using the DosOpen function. 


Return Value The return value is zero if the function is successful or an error value if an error 
occurs. 


See Also DosOpen, PRT_ACTIVATEFONT 


PTR_GETPTRDRAWADDRESS = 317 


m@ PTR_GETPTRDRAWADDRESS 


USHORT DosDevlOCtl( pbFunctioninfo, OL, 0x0072, 0x0003, hDevice) 
‘PBYTE pbFunctioninfo; /« pointer to structure for function »/ 


HFILE hDevice; 


Parameters 


Return Value 


Comments 


See Also 


/» device handle »/ 


The PTR_.GETPTRDRAWADDRESS function retrieves the entry-point address 
and other information for the pointer-draw function (the function that draws the 
mouse pointer on the screen). 


pbFunctionInfo Points to the PTRDRAWFUNCTION structure that receives 
the function information. The PFRDRAWFUNCTION structure has the follow- 
ing form: 
typedef struct _PTRDRAWFUNCTION { 

PEN pfnDraw; 


PCH pchDataSeg; 
} PTRDRAWFUNCTION; 


For a full description, see Chapter 4, “Types, Macros, Structures.” 


-hDevice Identifies the pointing device that receives the device-control func- 


tion. The handle must have been created previously by using the DosOpen func- 
tion. 


The return value is zero if the function is successful or an error value if an error 
occurs. 


The mouse device driver uses the pointer-draw function to update the pointer 
image on the screen, and retrieves the address and saves it to use whenever the 
pointer moves. 


DosOpen 


Chapter 
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4.1 Introduction 


This chapter describes the types, macros, and structures used with MS OS/2 
Dos, Kbd, Mou, and Vio functions. The MS OS/2 functions use many types, 
macros, and structures that are not part of the standard C language. These 
types, macros, and structures have been defined to make the task of creating MS 
OS/2 programs easier and to make program sources clearer and easier to under- 
stand. 


All types, macros, and structures in this manual are defined in the MS OS/2 C- 
language include files. Programmers may also wish to use these when developing 
MS OS/2 programs in other computer languages, such as Pascal or assembly- 
language. If include files for a given language are not available, a programmer 
can translate the definitions given in this chapter by following these guidelines: 


= Numbers must be integers or fixed-point real numbers. MS OS/2 functions 
do not support floating-point numbers. An MS OS/2 program can use 
floating-point numbers if an appropriate run-time library or coprocessor is 
supplied and if floating-point numbers are not used as parameters to the MS 
OS/2 functions. 


™ Structures must be packed. Some compilers align each new field in a struc- 
ture on word or double-word boundaries. This may leave unused bytes in a 
structure if a given field is smaller than the width between boundaries. MS 
OS/2 functions require that unused bytes be removed from structures. 


@ Reserved fields in structures should be set to zero. Unless otherwise speci- 
fied, MS OS/2 functions require that reserved fields be set to zero to avoid 
compatibility problems with future releases of MS OS/2. 


@ Variable-length structures must be supported. Several MS OS/2 functions 
use variable-length structures to receive and/or return information. In a 
variable-length structure, the number of fields varies depending on when the 
structure is used. In the C language, programs typically support variable- 
length structures by allocating enough memory for the current number of 
fields and accessing those fields by using a pointer to the structure. Programs 
in other languages may use this method or devise their own method for sup- 
porting variable-length structures. : 


= All 16-bit pointers must be relative to an explicitly defined segment register. 
Some compilers assume that the ds and ss registers contain the same value 
and implicitly use one segment for both. MS OS/2 does not guarantee that 
the ds and ss registers will be equal. This is especially true in dynamic-link 
eae and programs that use callback functions (for example, window pro- 
cedures 


@ All 32-bit pointers must consist of a selector:offset pair. A physical address, 
that is, an address that represents a 32-bit offset from the beginning of physi- 
cal memory, cannot be used by MS OS/2 functions. (One exception to this 
rule is the VioGetPhysBuf function, which requires a physical address to 
video memory.) 
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4.2 Types 


The following is a complete list, in alphabetical order, of the types that have 
been defined for the functions described in this manual. Many of these types 
begin with a letter that identifies what the type is used for—for example, H 

identifies a handle; P, a far pointer; NP, a near pointer; and U, an unsigned 


variable. . 
Type Meaning 
BOOL 16-bit Boolean value. © 
BYTE 8-bit unsigned value. 
CHAR 8-bit signed value. 
COLOR 32-bit signed value used to hold a color value. 
ERRORID 32-bit value used as an error identifier. 
FALSE Predefined constant set to zero. | 
HDC 32-bit value used as a device-context handle. 
HDIR 16-bit value used as a directory handle. | 
HFILE 16-bit value used as a file handle. 
HKBD 16-bit value used as a logical-keyboard handle. 
HMF 32-bit value used as a metafile handle. 
HMODULE 16-bit value used as a module handle. 
HMONITOR 16-bit value used as a monitor handle. 
HMOU 16-bit value used as a mouse handle. 
HPIPE 16-bit value used as a pipe handle. 
HPS 32-bit value used as a presentation-space handle. 
HQUEUE 16-bit value used as a queue handle. | 
HRGN 16-bit value used as a region handle. 
HSEM 32-bit value used as a semaphore handle. 
HSYSSEM 32-bit value used as a system semaphore handle. 
HTIMER 16-bit value used as a timer handle. | 
HVIO 16-bit value used as a video-device handle. 
INT 16-bit signed value. 
LONG 32-bit signed value. 
NPBYTE 16-bit pointer to an 8-bit unsigned value. 
NPCH 16-bit pointer to a value or array of values. 
NPFN | 


16-bit pointer to a function with pascal calling 
type. . 


Type 

NPSZ 

NULL 
PBOOL 
PBYTE 

PCH 
PCHAR 
PCOLOR 
PERRORID 
PFN . 


PFNSIGHANDLER 


PHDC 
PHDIR 
PHFILE 
PHKBD 
PHMF 
PHMODULE 
PHMONITOR 
PHMOU 
PHPIPE 

_ PHPS 
PHQUEUE 
PHRGN 
PHSEM 
PHSYSSEM 
PHTIMER 
PHVIO 

PID 

PINT 
PLONG 
PPID 

PSEL 
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_ Meaning 


16-bit pointer to a null-terminated string. 
Predefined null-pointer value set to zero. 
32-bit pointer to a Boolean value. 

32-bit pointer to an 8-bit unsigned value. 
32-bit pointer to a value or array of values. 
32-bit pointer to a value or array of values. 
32-bit pointer to a color value. 

32-bit pointer to an error identifier. 


32-bit pointer to a function with pascal calling 
type. 

32-bit pointer to a function with pascal calling 
type. 

32-bit pointer to a device-context handle. 
32-bit pointer to a directory handle. 

32-bit pointer to a file handle. 

32-bit pointer to a logical-keyboard handle. 
32-bit pointer to a metafile handle. 

32-bit pointer to a module handle. 

32-bit pointer to a monitor handle. 

32-bit pointer to a mouse handle. 

32-bit pointer to a pipe handle. 

32-bit pointer to a presentation-space handle. 
32-bit pointer to a queue handle. 

32-bit pointer to a region handle. 

32-bit pointer to a semaphore handle. . 
32-bit pointer to a system-semaphore handle. 
32-bit pointer to a timer handle. 

32-bit pointer to a video-device handle. 
16-bit value used to hold a process identifier. 
32-bit pointer to a 16-bit signed value. 

32-bit pointer to a 32-bit signed value. 

32-bit pointer to a process identifier. 


32-bit pointer to a selector. 
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4.3 Macros 


Type 
PSHORT 


HEH ee ES A tate a 


32-bit pointer to a 16-bit signed value. 


PSZ 
PTID 
PUCHAR 


PUINT 
PULONG 
PUSHORT 
PVOID 
SEL 
SHORT 
TID 
TRUE 
UCHAR 
UINT 
ULONG 
USHORT 


32-bit pointer to a null-terminated string. 
32-bit pointer to a thread identifier. 


32-bit. pointer to an unsigned value or array of 
values. 


32-bit pointer to a 16-bit unsigned value. 
32-bit pointer to a 32-bit unsigned value. 
32-bit pointer to a 16-bit unsigned value. 
32-bit pointer to an unspecified data type. 
16-bit value used to hold a segment selector. 
16-bit signed value. 

16-bit value used to hold a thread identifier. 
Predefined constant set to 1. 

8-bit unsigned value. 

16-bit unsigned value. 

32-bit unsigned value. 


16-bit unsigned value. 


The following is a complete list, in alphabetical order, of the macros that can be 
used with the functions described in this manual. 
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DEFINEMUXSEMLIST 
DEFINEMUXSEMLIST (name, size) 


The DEFINEMUXSEMLIST macro creates a structure that is used to hold the 
semaphore list for the DosMuxSemWait function. 


Parameters name Specifies the name of the structure to be created. 
size Specifies the size of the structure; that is, the number of semaphores in 
the list. 

See Also DosMuxSemWait 


FIELDOFFSET 
FIELDOFFSET ( type, field) 


The FIELDOFFSET macro computes the address offset of the specified field in 
the structure specified by the type parameter. 


Parameters type Specifies the name of the structure. 
field Specifies the name of a field defined within the given structure. 


HIBYTE 

HIBYTE(w) 
The HIBYTE macro retrieves the high-order unsigned byte from the 16-bit value 
specified by the w parameter. 

Parameters w Specifies a 16-bit value. 

See Also HIUCHAR, LOBYTE 

HIUCHAR 

HIUCHAR(w) 
The HIUCHAR macro retrieves the high-order unsigned byte from the 16-bit 
value specified by the w parameter. 

Parameters w Specifies a 16-bit value. 

See Also HIBYTE, LOUCHAR 

HIUSHORT 


HIUSHORT (/) 


The HIUSHORT macro retrieves the high-order, unsigned 16-bit word from the 
32-bit value specified by the / parameter. 
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Parameters l Specifies a 32-bit value. 
See Also LOUSHORT 

LOBYTE 

LOBYTE(w) 


The LOBYTE macro retrieves the low-order byte from the 16-bit value specified 
by the w parameter. 


Parameters w Specifies a 16-bit value. 
See Also HIBYTE, LOUCHAR 
LOUCHAR 

LOUCHAR(w) 


The LOUCHAR macro retrieves the low-order unsigned byte from the 16-bit 
value specified by the w parameter. 


Parameters w Specifies a 16-bit value. 
See Also HIUCHAR, LOBYTE 
LOUSHORT 

LOUSHORT (/) 


The LOUSHORT macro retrieves the low-order unsigned 16-bit word from the 
32-bit value specified by the / parameter. 


Parameters 1 Specifies a 32-bit value. 
See Also HIUSHORT 
MAKELONG 


MAKELONG (/, h) 


The MAKELONG macro combines two 16-bit word values to create a 32-bit long 
integer. 


Parameters | Specifies the low-order 16-bit word value for the new integer. 
h Specifies the high-order 16-bit word value for the new integer. 


See Also MAKESHORT, MAKEULONG 


m@ MAKEP 
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MAKEP (sel, off) 


Parameters 


See Also 


The MAKEP macro combines a segment selector and an address offset to create 
a far (32-bit) pointer to a memory address. 


sel Specifies a segment selector. It must be a valid segment selector—for 
example, if it were created by using the DosAllocSeg function. 


off Specifies an offset from the beginning of the given segment to the desired 
byte. The offset must specify an address within the segment. 


DosAllocSeg, OFFSETOF, SELECTOROF 


™@ MAKEPGINFOSEG 
MAKEPGINFOSEG (se/) 


Parameters 


Example 


See Also 


The MAKEPGINFOSEG macro creates a far (32-bit) pointer to the first byte in 
the global information segment. The macro assumes that the selector specified 
by the sel parameter has been retrieved by using the DosGetInfoSeg function. 


sel Specifies the segment selector of the global information segment. 


SEL selGlobalSeg, selLocalSeg; 

GINFOSEG FAR *pgis; 
DosGetInfoSeg(&selGlobalSeg, &selLocalSeg) ; 
pgis = MAKEPGINFOSEG(selGlobalSeg) ; 


DosGetInfoSeg, MAKEPLINFOSEG 


@ MAKEPLINFOSEG 


MAKEPLINFOSEG (se/) 


Parameters 
Example 


See Also 


The MAKEPLINFOSEG macro creates a far (32-bit) pointer to the first byte in 
the local information segment. The macro assumes that the selector specified by 
the sel parameter has been retrieved by using the DosGetInfoSeg function. 


sel Specifies the segment selector of the local information segment. 


SEL selGlobalSeg, selLocalSeg; 

LINFOSEG FAR *plis; 
DosGetInfoSeg(&selGlobalSeg, &selLocalSeg) ; 
lgis = MAKEPGINFOSEG(sel1GlobalSeg) ; 


DosGetInfoSeg, MAKEPGINFOSEG 
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MAKESHORT 
MAKESHORT (/, h) 


The MAKESHORT macro combines two 8-bit values to create a 16-bit integer. 


Parameters l Specifies the low-order 8-bit value of the new integer. 
h_ Specifies the high-order 8-bit value of the new integer. 

See Also MAKELONG, MAKEUSHORT 

MAKETYPE 


_ MAKETYPE(v, type) 


The MAKETYPE macro casts the variable specified by the v parameter as a vari- 
able having the type specified by the type parameter. This macro permits the 
contents of the variable to be accessed as if the variable had the specified type. 


Parameters v Specifies the name of the variable to be cast. 
type. Specifies the name of the data type for the cast. 


MAKEULONG 
MAKEULONG (/, h) 


The MAKEULONG macro combines two 16-bit values to create a 32-bit unsigned 


integer. 
Parameters 1 Specifies the low-order 16-bit value of the new integer. 

h_ Specifies the high-order 16-bit value of the new integer. 
See Also — MAKELONG, MAKEUSHORT 


MAKEUSHORT 
MAKEUSHORT (/, h) 


The MAKEUSHORT macro combines two &-bit values to create a 16-bit 
unsigned integer. 


Parameters I Specifies the low-order 8-bit value of the new integer. 
h_ Specifies the high-order 8-bit value of the new integer. 


See Also MAKESHORT, MAKEULONG 
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m™ OFFSETOF 
OFFSETOF(p) 
The OFFSETOF macro retrieves the address offset of the specified far pointer. 
Parameters p_ Specifies a far (32-bit) pointer. 
See Also SELECTOROF 


Mm SELECTOROF 
SELECTOROF(p) 


The SELECTOROF macro retrieves the selector from the specified far pointer. 
Parameters p_ Specifies a far (32-bit) pointer. 
See Also OFFSETOF 
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4.4 Structures 


The following is a complete list, in alphabetical order, of the structures used by 
the functions described in this manual. 


BIOSPARAMETERBLOCK 


™ BIOSPARAMETERBLOCK 


Fields 


typedef struct _BIOSPARAMETERBLOCK { /* bspblk */ 
USHORT usBytesPerSector ; 
BYTE bSectorsPerCluster ; 
USHORT usReservedSectors; 
BYTE cFATsS; 
USHORT cRootEntries; 
USHORT cSectors; 
BYTE bMedia:; 
USHORT usSectorsPerFAT; 
USHORT usSectorsPerTrack; 
USHORT cHeads; 
ULONG cHiddenSectors; 
ULONG cLargeSectors; 
BYTE abReserved [6]; 
USHORT cCylinders; 
BYTE bDeviceType; 
USHORT fsDeviceAttr; 

} BIOSPARAMETERBLOCK; 


The BIOSPARAMETERBLOCK structure contains BIOS parameter blocks. 


usBytesPerSector Specifies the bytes per sector. 
bSectorsPerCluster Specifies the sectors per cluster. 
usReservedSectors Specifies the reserved sectors. 
cFATs Specifies the number of file-allocation tables. 
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cRootEntries Specifies the maximum number of entries in the root directory. 


cSectors Specifies the number of sectors. 
bMedia Specifies the media descriptor. 


usSectorsPerFAT Specifies the number of sectors per file-allocation table. 


usSectorsPerTrack Specifies the number of sectors per track. 
cHeads_ Specifies the number of heads. 

cHiddenSectors Specifies the number of hidden sectors. 
cLargeSectors Specifies the number of large sectors. 
abReserved[6] Specifies six reserved bytes. These must be zero. 
cCylinders Specifies the number of cylinders defined for the device. 


bDeviceType Specifies the type of device. It can be one of the following 
values: 


Value Meaning 

DEVTYPE_48TPI 48 tracks-per-inch, low-density floppy-disk drive 
DEVTYPE_96TPI 96 tracks-per-inch; high-density floppy-disk drive 
DEVTYPE_35 3.5-inch (720K) floppy-disk drive 
DEVTYPE_8SD 8-inch, single-density floppy-disk drive 
DEVTYPE_8DD 8-inch, double-density floppy-disk drive 
DEVTYPE_FIXED Fixed disk 

DEVTYPE_TAPE Tape drive 


DEVTYPE_UNKNOWN Other (unknown type of device) 
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fsDeviceAttr Specifies information about the drive. If this value is 0x0001, the 
media are not removable. If it is 0x0002, the media can detect changes. This field 


Pe ae) eee 


os meen ae eee 
_ can be one or both of these values. 


See Also DSK_GETDEVICEPARAMS, DSK_SETDEVICEPARAMS 
CODEPAGEINFO 
, typedef struct _CODEPAGEINFO { /* cpi */ 
PBYTE pbTransTable; 
USHORT idCodePage; 
USHORT idTable; 
} CODEPAGEINFO; 
The CODEPAGEINFO structure specifies the code page and the translation 
table to be set. 
Fields pbTransTable Points to the keyboard translation table. 
idCodePage Specifies a code-page identifier. It can be one of the following 
values: . 
Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian ~ 
865 Nordic 
idTable Specifies the translation table to be replaced. If this value is OxFFFF, 
it specifies the custom translation table. 
See Also KBD_SETNLS 
COUNTRYCODE 
typedef struct _COUNTRYCODE { /* ctryc */ 
USHORT country; 
USHORT codepage; 
} COUNTRYCODE; 
The COUNTRYCODE structure contains the country code and code-page 
identifier. 
Fields country Specifies the country code. It can be one of the following values: 


Country code Country 


001 United States 


002 Canada (French) 
003 Latin America 
031 Netherlands 


032 Belgium 
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Country code Country 


033 France 

034 Spain 

039 Italy 

041 Switzerland (French) 
041 Switzerland (German) 
044 United Kingdom 
045 Denmark 

046 Sweden 

047 Norway 

049 Germany 

061 Australia 

351 Portugal 

358 Finland 


If this field is zero, the function uses the current country code. 
codepage Specifies the code-page identifier. It can be one of the following 


values: 
Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian 
865 Nordic 


If this field is zero, the function uses the current code-page identifier. 


See Also DosCaseMap, DosGetCollate, DosGetCtryInfo, DosGetDBCSEv 


™ COUNTRYINFO 


typedef struct _COUNTRYINFO { /* ctryi */ 
USHORT country; 
USHORT codepage; 
USHORT fsDateFmt; 
CHAR szCurrency [5]; 
CHAR szThousandsSeparator [2]; 
CHAR szDecimal [2]; 
CHAR szDateSeparator [2]; 
CHAR szTimeSeparator [2]; 
UCHAR fsCurrencyFmt; 
UCHAR cDecimalPlace; 
UCHAR fsTimeFmt; 
USHORT abReservedi1 [2]; 
CHAR szDataSeparator [2]; 
USHORT abReserved2 [5]; 
} COUNTRYINFO; 


The COUNTRYINFO structure contains country-dependent formatting informa- 
tion. 
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Fields country Specifies the country code. It can be one of the following values: 
Country code Country 
001 United States 
002 Canada (French) 
003 Latin America 
031 — Netherlands 
032 Belgium 
033 France 
034 Spain 
039 Italy 
041 Switzerland (French) 
041. Switzerland (German) 
044 United Kingdom 
045 Denmark 
046 Sweden 
047 Norway 
049 Germany 
061 Australia 
351 Portugal 
358 Finland 


codepage Specifies a reserved value; must be zero. 


fsDateF mt 
Value 
DATEFMT_MM_DD_YY 
DATEFMT_DD_MM_YY 
DATEFMT_YY_MM_DD 


szCurrency[5] 


terminated string. 
szDecimal[2] 


szDateSeparator[2] 
string. 


szTimeSeparator[2] 
string. 


fsCurrencyF mt 
the following values: 


Value 


CURRENCY_FOLLOW 


Specifies the date format. It can be one of the following values: 


Month, day, year (mm/dd/yy) 
Day, month, year (dd/mm/yy) 
Year, month, day (yy/mm/dd) 


Specifies the currency indicator. It is a null-terminated string. 


szThousandsSeparator[2] Specifies the thousands separator. It is a null- 


Specifies the decimal separator. It is a null-terminated string. 
Specifies the date separator. It is a null-terminated 


Specifies the time separator. It is a null-terminated 


Specifies the currency format. It can be any combination of 


Currency indicator follows the money value. If 
this value is not given, the currency indicator 
precedes the money value. 


See Also 


m@ CPID 


Fields 


See Also 
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Value Meaning 


CURRENCY_SPACE One space appears between the currency indica- 
tor and the money value. If this value is not 
given, no space appears between the currency 
indicator and the money value. 


CURRENCY_DECIMAL Specified currency indicator replaces the 
decimal indicator. If this value is given, other 
fsCurrencyFmt values are ignored. 


cDecimalPlace Specifies the number of decimal places (in binary) used in the 
currency value. 


fsTimeFmt Specifies the time format for file directory presentation. If this 
field is 0x0001, the time is presented in 24-hour (military-time) format. Other- 
wise, time is presented in a 12-hour format, with “a” and “p” used for A.M. and 
P.M. indicators. 


abReserved1[2] Specifies a reserved value; must be zero. 


szDataSeparator[2] Specifies a data-list separator. It is a null-terminated 
string. 


abReserved2[5] Specifies a reserved value; must be zero. 


DosGetCtryInfo 


typedef struct _CPID { /* cpid */ 
USHORT idCodePage; 
USHORT Reserved; 

} CPID; 


The CPID structure specifies the code-page identifier for a logical keyboard. 


idCodePage Specifies the code-page ID. It can be one of the following 
values: : 


Number Code page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


Reserved Specifies a reserved value; must be zero. 


KBD_GETCODEPAGEID 
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M@ DATETIME 
typedef struct DATETIME { /* date */ 
UCHAR hours; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
UCHAR day; 
UCHAR month; 
USHORT year; 
SHORT timezone; 
UCHAR weekday; 
} DATETIME; 
The DATETIME structure contains the date and time. 
Fields hours’ Specifies the current hour using values from 0 through 23. 
minutes Specifies the current minute using values from 0 through 59. 
seconds Specifies the current second using values from 0 through 59. 
hundredths Specifies the current hundredths of a second using values from 0 
through 99. 
day Specifies the current day of the month using values from 1 through 31. 
month Specifies the current month of the year using values from 1 through 12. 
year Specifies the current year. 
timezone Specifies the difference (in minutes) between the current time zone 
and Greenwich Mean Time (GMT). This field is positive for time zones west of 
Greenwich; it is negative for time zones east of Greenwich. For example, for 
Eastern Standard Time this field is 300 (that is, five hours, 5 x 60, after GMT). 
If this field is - 1, the time zone is undefined. 
weekday Specifies the current day of the week using values from 0 through 6 
(Sunday equals zero). 
See Also DosGetDateTime, DosSetDateTime 
m™ DCBINFO 
typedef struct _DCBINFO { /* dcbhinft */ 
USHORT usWriteTimeout; 
USHORT usReadTimeout; 
BYTE fbCtlHndShake; 
BYTE fbFlowReplace; 
BYTE fbTimeout; 
BYTE bErrorReplacementChar; 
BYTE bBreakReplacementChar; 
BYTE bXONChar ; 
BYTE bXOFFChar; 
} DCBINFO; 
The DCBINFO structure holds device-control block information. 
Fields usWriteTimeout Specifies the time-out in one-hundredths of a second. If set 


to zero, the time-out is 0.01 seconds; if set to 1, the time-out is 0.02 seconds, 
and so on. 


usReadTimeout Specifies the time-out in one-hundredths of a second. If set 
to zero, the time-out is 0.01 seconds; if set to 1, the time-out is 0.02 seconds, 
and so on. 


DCBINFO 
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fbCtlHndShake Specifies the control and handshaking modes for the DTR 
and other signals. It can be a combination of the following values: 


Value 


MODE_DTR_CONTROL 
MODE_DTR_HANDSHAKE 
MODE_CTS_HANDSHAKE 
MODE_DSR_HANDSHAKE 
MODE_DCD_HANDSHAKE 


MODE_DSR_SENSITIVITY 


Meaning 
Enable the data-terminal-ready (DTR) control 
mode. 


Enable the data-terminal-ready (DTR) input 
handshaking mode. 

Enable output handshaking using the clear- 
to-send (CTS) signal. 

Enable output handshaking using the data- 
set-ready (DSR) signal. 


Enable output handshaking using the data- 
carrier-detect (DCD) signal. 


Enable input sensitivity using the data-set- 
ready (DSR) signal. 


fbFlowReplace Specifies the flow control and replacement character modes. 
It can be a combination of the following values: 


Value 


MODE_AUTO_TRANSMIT 
MODE_AUTO_RECEIVE 


MODE_ERROR_CHAR 
MODE_NULL_STRIPPING 
MODE_BREAK_CHAR 

‘MODE_RTS_CONTROL 


MODE_RTS_HANDSHAKE 


MODE_TRANSMIT_TOGGLE 


Meaning 
Enable automatic transmit flow control 
(XON/XOFF). 


Enable automatic receive flow control 
(XON/XOFF). 


Enable error replacement character. 
Enable null stripping (remove null bytes). 
Enable break replacement character. 


Enable the request-to-send (RTS) control 
mode. 


Enable the request-to-send (RTS) input 
handshaking mode. . 


Enable toggling on transmit mode. 


fbTimeout Specifies the time-out processing for the device. It can be a com- 


bination of the following values: 
Value 


MODE_NO_WRITE_TIMEOUT 


Enable write infinite time-out 


processing. 
MODE_READ_TIMEOUT Enable normal read time-out 

processing. 
MODE_WAIT_READ_TIMEOUT Enable wait-for-something read 


time-out processing. 


MODE_NOWAIT_READ_TIMEOUT Enable no-wait read time-out 


processing. 


bErrorReplacementChar Specifies the error replacement character. 
bBreakReplacementChar Specifies the break replacement character. 
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See Also 


bXONChar Satiies the transmissio ( 
bXOFFChar = Specifies the transmission off (XOFF) character. 


ASYNC_GETDCBINFO, ASYNC_SETDCBINFO 


o 5 
care) 
o 8 


— DEVICEPARAMETERBLOCK 


Fields 


See Also 


™ DOSFSRSEM 


typedef struct _DEVICEPARAMETERBLOCK { /* avpblck */ 
USHORT reservedl; 
USHORT cCylinders; 
USHORT cHeads; . 
USHORT cSectorsPerTrack; 
USHORT reserved2; 
USHORT reserved3; 
USHORT reserved4; 
USHORT reserved5; 
} DEVICEPARAMETERBLOCK; 


The DEVICEPARAMETERBLOCK structure contains device parameters for the 
physical disk. 

reservedl Specifies a reserved value; must be zero. 

cCylinders Specifies the number of cylinders on the physical device. 

cHeads_ Specifies the number of heads on the physical device. 


cSectorsPerTrack Specifies the number of sectors per track on the physical 
device. 


reserved2- reservedS Specifies a reserved value; must be zero. 


PDSK_GETPHYSDEVICEPARAMS 


Fields 


typedef struct _DOSFSRSEM { 7* dosfsrs */ 
USHORT cb; 
PID pid; 
TID. tid; 


USHORT cUsage; 
USHORT client; 
ULONG” sem; 
} DOSFSRSEM; 


The DOSFSRSEM structure contains information for a fast- safe RAM sema- 
phore. 
cb Specifies the length of the structure (in bytes). It aia be set to 14. 


pid Specifies the process identifier of the process that owns the semaphore. If 
this field is zero, the semaphore is not owned. 


tid Specifies the thread identifier of the thread that owns the semaphore. 


cUsage Specifies the number of times the owner has issued a DosFSRamSem- 
Request function without a corresponding DosFSRamSemClear function. 


See Also 


m™ FDATE 
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client Specifies any owner-recorded information that may be needed through 
maintain the semaphore and the resource being managed. 


sem Specifies the RAM semaphore to be used in this request. 


DosFSRamSemClear, DosFSRamSemRequest 


Fields 


See Also 


@ FILEFINDBUF 


typedef struct _FDATE { /* fdate */ 
unsigned day 3s S$ 
unsigned month : 4; 
unsigned year 22S 

} FDATE; 


The FDATE structure is used in various other structures to specify the day, 
month, and year. 


day Specifies the day. 
month Specifies the month. 
year Specifies the year. 


FILEFINDBUF, FILESTATUS, FSINFO 


Fields 


typedef struct _FILEFINDBUF { /* findbuf */ 
FDATE fdateCreation; 
FTIME ftimeCreation; 
FDATE fdateLastAccess; 
ETIME ftimeLastAccess; 
FDATE fdateLastWrite; 
ETIME ftimeLastWrite; 
ULONG cbFile; 
ULONG cbFileAlloc; 
USHORT attrFile; 
UCHAR cchName; 
CHAR. achName [13]; 

} FILEFINDBUE ; 


The FILEFINDBUF structure contains information about a file. 


fdateCreation Specifies the date the file was created. 
ftimeCreation Specifies the time the file was created. 
fdateLastAccess | Specifies the date the file was last accessed. 
ftimeLastAccess Specifies the time the file was last accessed. 
fdateLastWrite Specifies the date the file was last written to. 
ftimeLastWrite Specifies the time the file was last written to. 
cbFile Specifies the end of file data. | 

cbFileAlloc Specifies the allocated file size. 

attrFile Specifies the file attributes. 
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echName Specifies the length of the null-terminated filename. 
achName[13] Specifies the null-terminated filename. 


See Also DosFindFirst, DosFindNext, FDATE, FTIME 


FILELOCK 


typedef struct  _FILELOCK { /* flock */ 
LONG 10ffset; 
LONG l1Range; 

} FILELOCK; 


The FILELOCK structure contains information about the starting position and 
number of bytes of a portion of a file to be locked or unlocked. 


Fields IFileOffset Specifies the offset from the beginning of the file to the start of 
the area to be locked or unlocked. 


IRangeLength Specifies the length of the locked or unlocked area (in bytes). 


See Also DosFileLocks 
FILESTATUS 
. typedef struct _FILESTATUS { /* fsts */ 
FDATE fdateCreation; 


FTIME ftimeCreation; 
FDATE fdateLastAccess; 
FTIME ftimeLastAccess; 
FDATE fdateLastWrite; 
FTIME ftimeLastWrite; 
ULONG cbFile; ‘ 
ULONG cbFileAlloc; 
USHORT attrFile; 

} FILESTATUS; 


The FILESTATUS structure contains information about the status of a file. 


Fields fdateCreation Specifies the date the file was created. 
ftimeCreation Specifies the time the file was created. 
fdateLastAccess Specifies the date the file was last accessed. 
ftimeLastAccess Specifies the time the file was last accessed. 
fdateLastWrite Specifies the date the file was last written to. 
ftimeLastWrite Specifies the time the file was last written to. 
cbFile Specifies the end of file data. 
cbFileAlloc Specifies the allocated file size. 


attrFile Specifies the file attributes. | 


Comments The cbFile, cbFileAlloc, and attrFile fields are not used by the DosSetFileInfo 
function. 


See Also DosQFileInfo, DosSetFileInfo 
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@ FONTINFO 
typedef struct _FONTINFO { /* finfo */ 
USHORT idCodePage; 
USHORT idFont; 
} FONTINEO; 
The FONTINFO structure specifies the code-page and font identifiers for a 
printer font. 
Fields idCodePage Specifies the code-page ID. It can be one of the following 
values: 
Number Code page 
437 United States 
850 Multilingual 
860 Portuguese 
863 French-Canadian 
865 Nordic 
idFont Specifies the font. The permitted font ID depends on the printer and 
on the loaded fonts. 
See Also PRT_ACTIVATEFONT, PRT_QUERYACTIVEFONT, PRT_VERIFYFONT 
m@ FRAME 
. typedef struct _FRAME { /* frm */ 
BYTE bCharsPerLine; 
BYTE bLinesPerInch; 
} FRAME; 
The FRAME structure contains frame-control information for a printer. 
Fields bCharsPerLine Specifies the number of characters on a line, either 80 or 
132. 
bLinesPerInch Specifies the number of lines per inch, either 6 or 8. 
See Also PRT_GETFRAMECTL, PRT_SETFRAMECTL 
mM FSALLOCATE 
typedef struct _FSALLOCATE { /* fsalloc */ 


ULONG idFileSystem; 
ULONG cSectorUnit; 
ULONG cUnit; 
ULONG cUnitAvail; 
USHORT cbSector; 

} FSALLOCATE; 


The FSALLOCATE structure contains information about a disk drive. 


Fields idFileSystem Specifies the file-system identifier. 
cSectorUnit Specifies the number of sectors per allocation unit. 
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cUnit Specifies the number of allocation units. 
cUnitAvail Specifies the available allocation units. 
cbSector Specifies the bytes per sector. 


See Also DosQFSInfo 


FSINFO 


typedef struct _FSINFO { /* fsinf */ 
FDATE fdateCreation; 
FTIME ftimeCreation; 
VOLUMELABEL vol; 

} EFSINFO; 


The FSINFO structure contains information about the volume label of a disk. 


Fields fdateCreation Specifies the date the volume label was created. 
. ftimeCreation Specifies the time the volume label was created. 


vol Specifies a VOLUMELABEL structure that will contain the name of the 
volume label. 


See Also DosQFSInfo, VOLUMELABEL 
FTIME | 
typedef struct _FTIME { /* ftime */ 
unsigned twosecs : 5; 
unsigned minutes : 6; 
unsigned hours S; 
} FTIME; 


The FTIME structure contains the time in seconds, minutes, and hours. 


Fields twosecs Specifies the number of seconds divided by two. To get the actual 
value, you must multiply it by two. For example, a value of 1 specifies 2 seconds, 
a value of 2 specifies 4 seconds, and so on. 


minutes Specifies the minutes. 
hours Specifies the hours. 


See Also FILEFINDBUF, FILESTATUS 


™ GINFOSEG 


Fields 
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typedef struct _GINFOSEG { 
ULONG time; 
ULONG msecs; 
UCHAR hour; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
USHORT timezone; 
USHORT cusecTimerInterval; 
UCHAR day; 
UCHAR month; 
USHORT year; 
UCHAR weekday; 
UCHAR uchMajorVersion; 
UCHAR uchMinorVersion; 
UCHAR chRevisionLetter ; 
UCHAR sgCurrent; 
UCHAR sgMax; 
UCHAR cHugeShift; 
UCHAR fProtectModeOnly; 
USHORT pidForeground; 
UCHAR fDynamicSched; 
UCHAR csecMaxwWait; 
USHORT cmsecMinSlice; 
USHORT cmsecMaxSlice; 
USHORT pbootdrive; 
UCHAR amecRAS [32]; 
UCHAR cesgWwindowableVioMax; 
UCHAR csgPMMax; 

} GINFOSEG; 


/* gis */ 


The GINFOSEG structure contains various global information. 


time Specifies the time from January 1, 1970 (in seconds). 

msecs Specifies the current system time (in milliseconds). 

hour Specifies the current hour using values from 0 through 23. 
minutes Specifies the current minute using values from 0 through 59. 
seconds Specifies the current second using values from 0 through 59. 


hundredths Specifies the current hundredths of a second using values from 0 
through 99. 


timezone Specifies the difference (in minutes) between the current time zone 
and Greenwich Mean Time (GMT). This field is positive for time zones west of 
Greenwich; it is negative for time zones east of Greenwich. For example, for 
Eastern Standard Time this field is 300 (that is, five hours, 5 x 60, after GMT). 
If this field is - 1, the time zone is undefined. 


cusecTimerInterval Specifies the timer interval (in milliseconds). 

day Specifies the current day of the month using values from 1 through 31. 
month Specifies the current month of the year using values from 1 through 12. 
year Specifies the current year. 


weekday Specifies the current day of the week using values from 0 through 6 
(Sunday equals zero). 


uchMajorVersion Specifies the major version number. 
uchMinorVersion Specifies the minor version number. 
chRevisionLetter Specifies the revision letter. 
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sgCurrent Specifies the current foreground screen group. 
sgMax_ Specifies the maximum number of screen groups. | 
cHugeShift Specifies the shift count for huge segments. 
fProtectModeOnly Specifies the protected-mode-only indicator. 
pidForeground Specifies the identifier of the current foreground process. 
fDynamicSched Specifies the dynamic variation flag (1 equals enabled). 
csecMaxWait Specifies the maximum wait (in seconds). 
cmsecMinSlice Specifies the minimum time slice (in milliseconds). 
emsecMaxSlice Specifies the maximum time slice (in milliseconds). 
bootdrive Specifies the boot drive. 
amecRAS[32] Specifies that each bit corresponds to a system-trace major 
code from 0x0000 through OxOOFF. The most significant bit (leftmost) of the first 
byte in the array corresponds to major code 0x0000. If a bit is cleared, the trace 
is disabled. If a bit is set, the trace is enabled. 
cesgWindowableVioMax Specifies the maximum number of VIO window- 
compatible sessions. 
csgPMMax Specifies the maximum number of Presentation Manager ses- 
sions. 
See Also DosGetInfoSeg, LINFOSEG 
m@ HOTKEY 
typedef struct _HOTKEY { /* htky */ 
USHORT fsHotKey; 
UCHAR uchScancodeMake; 
UCHAR uchScancodeBreak; 
USHORT idHotKey; 
} HOTKEY; 
The HOTKEY structure contains information for the session-manager hot key. 
Fields fsHotKey Specifies the setting for the session-manager hot key. It can be a 


combination of the following values: 


Value Meaning 

RIGHTSHIFT Right SHIFT key down. 
LEFTSHIFT Left SHIFT key down. 
LEFTCONTROL Left CONTROL key down. 
LEFTALT Left ALT key down. 
RIGHTCONTROL Right CONTROL key down. 
RIGHTALT Right ALT key down. 
SCROLLLOCK SCROLL LOCK key down. 
NUMLOCK NUMLOCK key down. 
CAPSLOCK CAPSLOCK key down. 
SYSREQ SYSREQ key down. 


Comments 


See Also 


—@ KBDINFO 


Fields 
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uchScancodeMake Specifies the scan code of the hot-key “make.” If this 
field is given, the system detects the hot key when the user presses the key that 
generates this scan code. . 


uchScancodeBreak Specifies the scan code of the hot-key “break.” If this 
field is given, the system detects the hot key when the user releases the key that 
generates this scan code. 


idHotKey Specifies the session-manager hot-key identifier. It must be a value 
from 0 through 15. 


The scancodeMake and scancodeBreak fields are mutually exclusive; only one 
may be specified. 


KBD_GETSESMGRHOTKEY, KBD_SETSESMGRHOTKEY 


typedef struct _KBDINFO { /* kbst */ 
_ USHORT cb; 
USHORT fsMask; 
USHORT chTurnAround; 
USHORT fsInterim; 
USHORT fsState; 
} KBDINEFO; 


The KBDINFO structure contains status information for a logical keyboard. 


cb = Specifies the length (in bytes) of the KBDINFO structure. It must be set 
to 10. 


fsMask Specifies the current keyboard modes. It can be a combination of the 
following values: 


. Value Meaning 
KEYBOARD_ECHO_ON Echo mode turned on. 
KEYBOARD_ECHO_OFF Echo mode turned off. 
KEYBOARD_BINARY_MODE Binary mode turned on. 
KEYBOARD_ASCII_MODE ASCII mode turned on. 
KEYBOARD_MODIFY_STATE The fsState field is to be 


modified. Applies to the 
KbdSetStatus function only. 
KEYBOARD_MODIFY_INTERIM The fsInterim field is to be 
modified. Applies to the 
KbdSetStatus function only. 
KEYBOARD_MODIFY_TURNAROUND _ The chTurnAround field is to 
be modified. Applies to the 
KbdSetStatus function only. 
KEYBOARD_2B_TURNAROUND Two-byte turn-around charac- 
ter. If not given, the turn- 
around character is one byte. 


KEYBOARD_SHIFT_REPORT Shift reporting turned on. 
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KBDINFO 


See Also 


™@ KBDKEYINFO 


Note that echo mode is either turned on or off. Only one input mode, ‘binary or 
ASCII, can be turned on at any given time. 


chTurnAround Specifies the turn-around character. If this field value 
includes 0x0080, the character is two-bytes packed in the low and high bytes 
of this field. Otherwise, the character is a single byte i in the low byte. 


fsInterim Specifies the interim character flags. If this field is 0x0020, the pro- 
gram has requested character conversion. If it is 0x0080, the interim character 
flagison. | 


fsState Specifies the state of the shift keys. It can be any combination of the 
following values: 


Value Meaning 

RIGHTSHIFT Right sHIFT key down. 
LEFTSHIFT Left SHIFT key down. 
CONTROL CONTROL key down. 

ALT ALT key down. 
SCROLLLOCK_ON SCROLL LOCK mode turned on. 
NUMLOCK_ON NUMLOCK mode turned on. 
CAPSLOCK_ON CAPSLOCK mode turned on. 


INSERT_ON INSERT mode turned on. 
KbdGetStatus, KbdSetStatus 


Fields 


typedef struct _KBDKEYINFO a /* kboci */ 
UCHAR chChar; 
UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNisShift; 
USHORT fsState; 
ULONG time; 
} KBDKEYINEFO; 


The KBDKEYINFO structure contains information when a key is pressed. 


chChar Specifies the character derived from translation of the chScan field. 


chScan Specifies the scan code received from the keyboard, identifying the 
key pressed. This scan code may be modified during the translation process. 


fb Status Specifies the state of the retrieved scan n code. It can be any combina-_ 
tion of the following values: 


Value Meaning 

SHIFT_KEY_IN Shift key is received (valid only in binary 
mode when shift reporting is turned on). 

CONVERSION_REQUEST Conversion requested. 

FIN AL_CHAR_IN . Final character received. 

INTERIM_CHAR_IN Interim character received. 


bNisShift Specifies a reserved value; must be zero. 


fsState 
following values: 


time 


Value 


RIGHTSHIFT 
LEFTSHIFT 
CONTROL 

ALT 
SCROLLLOCK_ON 
NUMLOCK_ON 
CAPSLOCK_ON 
INSERT_ON 
LEFTCONTROL 


~LEFTALT 


RIGHTCONTROL 
RIGHTALT 
SCROLLLOCK 
NUMLOCK 
CAPSLOCK 
SYSREQ 


Meaning 


Right SHIFT key down. 
Left SHIFT key down. 


Either CONTROL key down. 


Either ALT key down. 


SCROLL LOCK mode turned on. 
NUMLOCK mode turned on. 


CAPSLOCK mode turned on. 


INSERT key turned on. 


Left CONTROL key down. 


Left ALT key down. 


Right CONTROL key down. 


Right ALT key down. 


SCROLL LOCK key down. 


NUMLOCK key down. | 
CAPSLOCK key down. 
SYSREQ key down. 


KBDTYPE 


Specifies the time stamp of the keystroke (in milliseconds). 
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Specifies the state of the shift keys. It can be any combination of the 


See Also KbdCharIn, KbdPeek, KBD_PEEKCHAR 
@ KBDTYPE 
typedef struct _KBDTYPE { /* kbdtyp */ 
USHORT usType; 
USHORT reserved1; 
USHORT reserved2; 
} KBDTYPE; 
The KBDTYPE structure contains information about the keyboard type. 
Fields usType Specifies the keyboard type. If this field is 0x0000, an IBM PC/AT 


See Also 


Specifies a reserved value; must be zero. 
reserved2 Specifies a reserved value; must be zero. 


KBD_GETKEYBDTYPE 


keyboard is specified. If it is 0x0001, an IBM enhanced keyboard is specified. 
Values from 0x0002 to 0x0007 are reserved for Japanese keyboards. 


reservedl 
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—H KBDTRANS 


Fields 


UCHAR chScan; 
UCHAR fbStatus; 
UCHAR bNisShift; 
USHORT fsState; . 
ULONG time; 
USHORT fsDD; 
USHORT fsXlate; 
USHORT fsShift; 
USHORT sZero; 

} KBDTRANS; 


The KBDTRANS structure contains translated character information. 
chChar Specifies the character value of the translated scan code. The func- 


tion copies the value to this field before returning. 


chSean Specifies the scan code of the keystroke to be translated. This field 
must be set before the function is called. 


fbStatus Specifies the state of the returned scan code. It can be any combina- 
tion of the following values: 


ea he a ee 

SHIFT_KEY_IN Shift key received (valid only in binary mode 
when shift reporting is turned on). 

CONVERSION_REQUEST Conversion requested. 

FINAL_CHAR_IN Final character received. 

INTERIM_CHAR_IN Interim character received. 


bNIsShift Specifies a reserved value; must be zero. 


fsState Specifies the state of the shift keys. It can be one of the following 
values: 


Value Meaning 

RIGHTSHIFT Right SHIFT key down. 
LEFTSHIFT Left SHIFT key down. 
CONTROL Either CONTROL key down. 
ALT | Either ALT key down. 
SCROLLLOCK_ON SCROLL LOCK mode turned on. 
NUMLOCK_ON NUMLOCK mode turned on. 
CAPSLOCK_ON CAPSLOCK mode turned on. 
INSERT_ON INSERT mode turned on. 
LEFTCONTROL Left CONTROL key down. 
LEFTALT Left ALT key down. 
RIGHTCONTROL Right CONTROL key down. 
RIGHTALT Right ALT key down. 
SCROLLLOCK SCROLL LOCK key down. 
NUMLOCK _ NUMLOCK key down. 
CAPSLOCK CAPSLOCK key down. 


SYSREQ SYSREQ key down. 
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time Specifies the time stamp of the keystroke (in milliseconds). 


fsDD Defined for monitor packets. For more information, see the DosMon- 
Reg function. 


fsXlate Specifies the translation flags. If this field is 0x0000, translation is 
incomplete. If it is 0x0001, translation is complete. 


fsShift Specifies the state of translation across successive calls. Initially, this 
field should be zero. It should be reset to zero when the caller wants to start a 

new translation. Note that it may take several calls to the KbdXlate function to 
complete a character, so this field should not be changed unless a new transla- 

tion is desired. This field is cleared when translation is complete. 


sZero Specifies a reserved value; must be zero. 


See Also DosMonReg, KbdXlate 


m@ LINECONTROL 


typedef struct _LINECONTROL { /* Inctl */ 
BYTE bDataBits; 
BYTE bParity; 
BYTE bStopBits; 
BYTE fbTransBreak; 
} LINECONTROL; 


The LINECONTROL structure contains line characteristics for a device. 


Fields bDataBits Specifies the number of data bits to be used. It can be one of the 

following values: 

Value Meaning 

0x05 5 data bits 

0x06 6 data bits 

0x07 7 data bits 

0x08 8 data bits 
bParity Specifies the type of parity checking. It can be one of the following 
values: 

. Value Meaning 

0x00 No parity 

0x01 Odd parity 

0x02 Even parity 

0x03 Mark parity (parity bit always 1) 


0x04 Space parity (parity bit always 0) 
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bStopBits Specifies the number of stop bits used. It can be one of the follow- 


ing values: — 
Value Meaning 
0x00 1 stop bit 
0x01 1.5 stop bits (valid only with 5-bit word length) 
0x02 2 stop bits (not valid with 5-bit word length) 


fbTransBreak Specifies whether the device is transmitting a break character. 
If this field is 0x00, a break character is not transmitted. If it is 0x01, a break 
character is transmitted. 


Comments The ASYNC_GETLINECTRL function (0x0001, 0x0062) uses all four bytes. 
The ASYNC_SETLINECTRL function (0x0001, 0x0042) uses only the first three 
bytes. 

See Also ASYNC_GETLINECTRL, ASYNC_SETLINECTRL 

m@ LINFOSEG 
typedef struct _LINFOSEG { /* lis */ 
PID pidCurrent; 
PID pidParent; 
USHORT prtyCurrent; 
TID tidCurrent; 


USHORT sgCurrent; 
UCHAR rfProcStatus; 
UCHAR dummy 1 ; 
BOOL fForeground; 
UCHAR typeProcess; 
UCHAR dummy2; 
SEL selEnvironment; 
USHORT, offCmdLine; 
USHORT cbhDataSegment; 
USHORT cbStack; 
USHORT cbHeap; 
HMODULE hmod; 
SEL selDS; 

} LINEFOSEG; 


The LINFOSEG structure contains information local to the current process. 


Fields pidCurrent Specifies the identifier of the current process. 
. pidParent Specifies the identifier of the parent process. 

prtyCurrent Specifies the priority of the current thread. 

tidCurrent Specifies the identifier of the current thread. 

sgCurrent Specifies the current screen group. 

rfProcStatus Specifies the subscreen group. 

dummyl__ Reserved. 

fForeground Specifies that the current process is in foreground. 

typeProcess Specifies the process type. It can be one of the following values: 
Value Meaning 
0 Process is running in a full-screen protected mode session. 


1 Process is running in the compatibility box. 


MODEMSTATUS = 351 


Value Meaning 

2 Process is running in a VIO-windowed session. 

3 Process is running in the Presentation Manager screen group. 
4 Process is running as a detached process. 


dummy2_ Reserved. 


selEnvironment Specifies the selector to the application’s copy of the 
environment. 


offCmdLine Specifies the offset to the environment where the command line 
that is used to run the current application is copied. 


cbDataSegment Specifies the size of the default data segment. 
cbStack Specifies the size of the stack. 

cbHeap Specifies the size of the heap. 

hmod Identifies the program. 

seIDS Specifies the default data segment. 


Comments The following fields are contained in registers at startup: 
Field Register 
SelEnvironment ax 
offCmdLine bx 
cbDataSegment cx 
cbStack dx 
cbHeap si 
hmod di 
seIDS ds 
See Also ‘DosGetInfoSeg, GINFOSEG 


™ MODEMSTATUS 


typedef struct _MODEMSTATUS { /* mamst */ 
BYTE fbModemOn; 
BYTE fbModemOff; 

} MODEMSTATUS; 


The MODEMSTATUS structure contains information about modem-control 


signals. 
Fields fbModemOn_ Specifies the modem-control signals to be enabled. It can be 
one or both of the following values: 
Value Meaning 
DTR_ON Data-terminal-ready (DTR) signal enabled. 
RTS_ON Ready-to-transmit (RTS) signal enabled. 


IE it is 0x00, no signals are enabled. 
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fbModemOff Specifies the modem-control signals to be disabled. It can be 
one or both of the following values: 


Value Meaning 


DTR_OFF Data-terminal-ready (RTR) signal disabled. 
RTS_OFF Ready-to-transmit (RTS) signal disabled. 


If it is OxFF, no signals are enabled. 


Comments Any values other than those specified for the fhModemOn and fhbModemOff 
fields will cause an error value. 
See Also ASYNC_SETMODEMCTRL 
MONIN 
typedef struct _MONIN { 7* mnin */ 
USHORT cb; 


BYTE abReserved [18]; 
BYTE abBuffer [108]; 
} MONIN; 


The MONIN structure contains monitor-input information. 


Fields cb = Specifies the length of the structure (in bytes). The structure must be at 
least 64 bytes; 128 bytes is the recommended length. 
abReserved[18] Specifies a reserved space. 


abBuffer[108] Specifies a buffer area which must be greater than or equal to 
the buffer used by the device driver. 


See Also DosMonReg 
MONITORPOSITION 
typedef struct _MONITORPOSITION { /* mnpos */ 


USHORT fPosition; 

USHORT index; 

PBYTE pbInBuf; 

USHORT of fOutBuf:; y 
} MONITORPOSITION; 


The MONITORPOSITION structure contains information about a monitor. 


Fields fposition Specifies the position-flag parameter used in the DosMonReg func- 
. tion. It can be one of the following values: 
Value Meaning 


MONITOR_DEFAULT Place the monitor anywhere in the chain. 


MONITOR_BEGIN Place the monitor at the beginning of the chain, in 
front of any other monitors already in the chain. 
MONITOR_END Place the monitor at the end of the chain, after any 


other monitors already in the chain. 
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index Specifies a device-specific value. 


pbInBuf Points to the monitor-input buffer that is initialized by the monitor 
dispatcher and used by the DosMonRead function. 


offOutBuf Specifies the offset to the monitor-output buffer that is initialized 
by the monitor dispatcher and used by the DosMonWrite function. 


See Also DosMonRead, DosMonReg, DosMonWrite, MON_.REGISTERMONITOR 
MONOUT 
typedef struct _MONOUT { /* mnout */ 
USHORT cb; 


BYTE abReserved [18]; 
BYTE abBuffer [108]; 
} MONOUT; 


The MONOUT structure contains monitor-output information. 


Fields cb = Specifies the length of the structure (in bytes). The structure must be at 
least 64 bytes; 128 bytes is the recommended length. 
abReserved[18] Specifies a reserved space. — 


abBuffer[108] Specifies a buffer area which must be greater than or equal to 
the buffer used by the device driver. 


See Also DosMonReg 
MOUEVENTINFO 
typedef struct _MOUEVENTINFO { /* mouev */ 
USHORT fs; : 


ULONG time; 
USHORT row; 
USHORT col; 
} MOUEVENTINEFO; 


The MOUEVENTINFO structure contains information about a mouse event. 


Fields fs Specifies the action that generated the mouse event. It can be any combina- 
tion of the following values: : 
Value Meaning 
MOUSE_MOTION Mouse moved with no buttons 
down. 
MOUSE_MOTION_WITH_BN1_DOWN Mouse moved with button 1 
oo down. 


MOUSE_BN1_DOWN Button 1 down. 
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MOUSE_BN2_DOWN 
MOUSE_MOTION_WITH_BN3_DOWN 


MOUSE_BN3_DOWN 


Meankd 
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down. 

Button 2 down. 


Mouse moved with button 3 
down. 


Button 3 down. 


If the mouse button is released with no motion, this field is zero. 

time Specifies the number of milliseconds since MS OS/2 was booted. 
row Specifies the x-coordinate of the mouse. : 
col Specifies the y-coordinate of the mouse. 


See Also MouReadEventQue 


MOUQUEINFO 


typedef struct _MOUQUEINFO { /* mouqi */ 


USHORT cEvents; 
USHORT cmaxEvents; 
} MOUQUEINEO; 


The MOUQUEINFO structure contains information about the mouse queue. 


Fields cEvents Specifies the number of event-queue elements. It can 1 be any value 
between zero and the maximum queue size. 


cmaxEvents Specifies the maximum queue size (the maximum number of 
queue elements). 


See Also MouGetNumQueEFl 


MUXSEM 


eypeaee struct _MUXSEM { 


/* mxs */ 
USHORT zero; 7 


HSEM hsem; 
} MUXSEM; 


The MUXSEM structure contains the semaphore used in the MUXSEMLIST 
structure. 


Fields zero Specifies a reserved value; must be zero. 


hsem Identifies the semaphore. The handle must have been created previously 
by using the DosCreateSem or DosOpenSem function. 


See Also DosCreateSem, DosOpenSem, MUXSEMLIST © 


™ MUXSEMLIST 


Fields 


See Also 


m™ NOPTRRECT 
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typedef struct _MUXSEMLIST { /* mxsl */ 
USHORT cmxs; 
MUXSEM amxs [16]; 

} MUXSEMLIST; 


The MUXSEMLIST structure contains a list of up to 16 semaphores. 


cmxs Specifies the number of semaphores in the list. 
amxs[16] Specifies an array of MUXSEM structures. 


DosMuxSemWait, MUXSEM 


Fields 


Comments 


See Also 


typedef struct _NOPTRRECT { /* mourt */ 
USHORT row: 
USHORT col; 
USHORT cRow; 
USHORT cCol; 
} NOPTRRECT; 


The NOPTRRECT structure contains the exclusion rectangle for the mouse. 


row Specifies the x-coordinate of the upper-left corner. 

col Specifies the y-coordinate of the upper-left corner. 

cRow  Specifiés the x-coordinate of the lower-right corner. 

cCol Specifies the y-coordinate of the lower-right corner. 

The units for these fields depénd on the current video mode. For text mode, 
values are given in character cells. For graphics mode, values are given in pels. 


The fields must not exceed the minimum and maximum coordinate values for 
screen height and width. 


MouRemovePtr 
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— PIDINFO. 


Fields 


See Also 


m@ PIPEINFO 


typedef struct _PIDINFO { /* pidi */ 
ID pid; 
TID tid; 
» PID pidParent; 
} PIDINEO; 


The PIDINFO structure contains process identifiers. 


pid Specifies the process identifier of the calling process. 
tid ‘Specifies the thread identifier of the calling thread. 


pidParent Specifies the process identifier of the parent process of the calling 
process. 


DosGetPID 


Fields 


See Also 


cypeces struct _PIPEINFO { /* nmpinf */ 
USHORT cbOut; 
USHORT cbIn; 
BYTE cbMaxInst; 
BYTE ecbCurInst; 
BYTE cbName; 
CHAR szName[1]; 
} PIPEINFO; 
The PIPEINFO structure contains named-pipe information retrieved by using the 
DosQNmPipelInfo function. The length of the structure varies depending on the 
length of the szName field. 


cbOut Specifies the size of the buffer for outgoing data. 
cbIn Specifies the size of the buffer for incoming data. 


cbMaxInst Specifies the maximum number of pipe instances that can be 
created. 


cbCurlInst Specifies the number of current pipe instances. 
cbName_ Specifies the length of the pipe name. 


szName[1] Contains a null-terminated string with the pipe name, including 
the computer name if the pipe is remote. 


DosQNmPipeInfo 
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m@ PTRACEBUF 


typedef struct _PTRACEBUF { /* ptrebf */ 
PID pid: 
TID tid; 


USHORT cmd; 
USHORT value; 
USHORT offv; 
USHORT segv; 
USHORT mte; 
USHORT rAX; 
USHORT rBX; 
USHORT rCx; 
USHORT rDX; 
USHORT rSI; 
USHORT rDI; 
USHORT rBP; 
USHORT rDS; 
USHORT rES; 
USHORT rIP; 
USHORT rCS; 
USHORT rF; 
USHORT rSP; 
USHORT rSS; 
} PTRACEBUE; 


The PTRACEBUF structure contains various debugging information. 


Fields pid Specifies the process identifier of the program being debugged. 
tid Specifies the thread identifier of the program being debugged. 
cmd _ Specifies the command to carry out. It can be one of the following 


values: 

Value Meaning 
0x0001 Read memory I-space. 
0x0002 Read memory D-space. 

. 0x0003 Read registers. 
0x0004 Write memory I-space. 
0x0005 Write memory D-space. 
0x0006 Write registers. 
0x0007 Go (with signal). 
0x0008 Terminate child process. 
0x0009 Single step. 
O0x000A Stop child process. 
0x000B Freeze child process. 
0x000C Resume child process. 
0x000D Convert segment number to selector. 
0x000E Get floating-point registers. The segy and offv fields must 


specify the address of a 94-byte buffer that receives the 
floating-point register values. 
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PTRACEBUF 


Value 


AL AAA 


UXUUUP 


0x0010 


Set fioating-point registers. The segv and offv fields must 
specify the address of a 94-byte buffer that contains the 
floating-point register values. 


Get library-module name. The value field must contain the 
handle of the library module. The segv and offy fields must 
contain the address of the buffer that receives the name. This 
command should be used instead of the DosGetModHandle 
and DosGetModName functions to verify the name of a library 
loaded by the program being debugged. 


When the function returns, it copies a code that specifies the command 
result to the field. The return code can be one of the following values: 


Value 


0x0000 
OxFFFF 
OxFFFE 
OxFFFD 
OxFFFC 
OxFFFB 
OxFFFA 
OxFFF9 


OxFFF8 


OxFFF7 


Meaning 


Success return code. 

Error. The error code is in the value field. 
About to receive signal. 

Single-step interrupt. 

Hit break point. 

Parity error. 

Process dying. 


General protection fault occurred. The fault type is in the 
value field. The segv and offv fields contain the address that 
caused the fault. 


Library module has just been loaded. The value field contains 
the library-module handle. 


Process has not used 287 yet. 


value Specifies the value to be used for a given command, or a return value 
from a command. If an error occurs, the field is set to one of the following 


values: 
Value 


0x0001 
0x0002 
0x0005 


Bad command. | 
Child process not found. 


Child process untraceable. 


offv Specifies the offset from the given segment. 

segv Specifies a segment selector. 

mte Specifies the module handle that contains the segment. 
rAX Specifies the ax register. 


rBX Specifies the bx register. 


rCX Specifies the ex register. 
rDX Specifies the dx register. 
rSI Specifies the si register. 
rDI Specifies the di register. 


See Also 
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rBP Specifies the bp register. 
rDS__ Specifies the ds register. 
rES Specifies the es register. 
rIP Specifies the ip register. 
rCS__ Specifies the es register. 
rF Specifies flags. 

rSP Specifies the sp register. 
rSS__ Specifies the ss register. 


DosGetModHandle, DosGetModName, DosPTrace 


PTRDRAWFUNCTION 


Fields 


See Also 


PTRLOC 


typedef struct _PTRDRAWFUNCTION { /* ptrdfne */ 
PEN pfnDraw; 
PCH pchDataSeg; 

} PTRDRAWFUNCTION; 


The PTRDRAWFUNCTION structure contains information about a pointer-draw 
function. 


pfnDraw Points to the pointer-draw function. 
pcehDataSeg Points to the data segment of the pointer-draw function. 


MOU_SETPROTDRAWADDRESS, MOU_SETREALDRAWADDRESS, 
PTR_GETPTRDRA WADDRESSFUNCTION 


Fields 


Comments 


See Also 


typedef struct _PTRLOC { /* moupl */ 
USHORT row; 
USHORT col; 

} PTRLOC; 


The PTRLOC structure contains the position of the mouse. 


row Specifies the x-coordinate of the mouse. 


col Specifies the y-coordinate of the mouse. 


The values of the row and col fields depend on the current video mode of the 
screen (as defined by the VioSetMode function). For text mode, values are given 
in character cells. For graphics mode, values are given in pels. 


MouGetPtrPos, MouSetPtrPos, VioSetMode 
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PTRSHAPE 


typedef struct _PTRSHAPE { 
USHORT cb; 


/* moups */ 


USHORT col; 

USHORT row; 

USHORT colHot; 

USHORT rowHot; 
} PTRSHAPE ; 


The PTRSHAPE structure contains information about the shape of the mouse. 


Fields cb = Specifies the length in bytes of the AND and XOR masks. 


col Specifies the width of each mask. For text mode, the width is given in 
character cells. For graphics mode, the width is given in pels. This value must be 
greater than or equal to 1. 


row Specifies the height of each mask. For text mode, the width is given in 
character cells. For graphics mode, the height is given in pels. This value must 
be greater than or equal to 1. 


colHot Specifies the horizontal offset from the upper-left corner of the 


pointer shape to the hot spot. For text mode, the offset is given in character 
cells. For graphics mode, the offset is given in pels. 


rowHot Specifies the vertical offset from the upper-left corner of the pointer 
shape to the hot spot. For text mode, the offset is given in character cells. For 
graphics mode, the offset is given in pels. 


Comments The cb field of this structure is always equal to the height times the width (row x 
col). If the current video mode requires multiple bit planes, the row and col 
fields specify the width and height of the first plane only, but the function copies 
all bit planes to the specified buffer. 


See Also MouGetPtrShape, MouSetPtrShape 


QUEUERESULT 


typedef struct _QUEUERESULT { /* qrese */ 
PID pidProcess;. 
USHORT usEventCode; 

} QUEUERESULT; 


The QUEUERESULT structure contains the result of a queue-reading operation. — 


Fields pidProcess Specifies the process identifier of the process that added the ele- 
ment to the queue. 


usEventCode Specifies a program-supplied event code. MS OS/2 does not 
use this field and reserves it for any use a program may make of it. 


See Also DosPeekQueue, DosReadQueue 
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™@ RATEDELAY 


typedef struct WRATEDELAY { /* rtdly */ 
USHORT usDelay; 
USHORT usRate; 

} RATEDELAY; 


The RATEDELAY structure contains typamatic information. 


Fields usDelay Specifies the typamatic delay (in milliseconds). A value greater than 
the maximum value defaults to the maximum value. 


usRate Specifies the typamatic rate (characters-per-second). A value greater 
than the maximum value defaults to the maximum value. 


See Also KBD_SETTYPAMATICRATE 


m™ RESULTCODES 


typedef struct _RESULTCODES { /* resco */ 
USHORT codeTerminate; 
USHORT codeResult; 

} RESULTCODES; 


The RESULTCODES structure contains the results of a process when it ter- 
minates. : 


Fields codeTerminate _ Specifies the child-process identifier if the child process is 
asynchronous. Otherwise, it specifies the termination code of the child process. 
The termination code can be one of the following values: 


Value Meaning 
TC_EXIT Normal exit 
TC_HARDERROR Hard-error termination 
TC_TRAP Trap operation 
._ TC_KILLPROCESS Unintercepted DosKillProcess function 


codeResult Specifies the result code of the:terminating process in its last call 
to the DosExit function. Specifies the exit code of the child process if the child 
process is synchronous. This field is not used for an asynchronous child process. 

a exit code is specified in the last call by the child process to the DosExit 
unction. 


See Also DosCwait, DosExecPgm, DosExit, DosKillProcess 


™ RXQUEUE 


typedef struct _RXQUEUE { /* rxq */ 
USHORT cch; 
USHORT cb; 

} RXQUEUE; 


The RXQUEUE structure contains the number of characters in the queue and 
the size of the queue. 
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Fields cch Specifies the number of characters received or to be transmitted in the 
device-driver queue. 


cb Specifies the size of the queue (in bytes). 
See Also ASYNC_GETINQUECOUNT, ASYNC_GETOUTQUECOUNT 


SCALEFACT | 


typedef struct _SCALEFACT { /* mouse */ 
USHORT rowScale; 
USHORT colScale; 

} SCALEFACT; 


The SCALEFACT structure contains information for scaling the mouse. 
Fields rowScale Specifies the vertical scaling factor (the number of mickeys the 
mouse must move to change the vertical mouse position by one screen unit). 
colScale Specifies the horizontal scaling factor (the number of mickeys the 
mouse must move to change the horizontal mouse position by one screen unit). 


Comments The rowScale and colScale fields specify mickeys and will always be in the range 
1 through 32,767. The screen units may be character cells or pels, depending on 
the current video mode. 


See Also MouGetScaleFact, MouSetScaleFact 
SCREENGROUP 
toueder struct _SCREENGROUP { /* sergrp */ 


USHORT idScreenGrp; 
USHORT fTerminate; 
} SCREENGROUP; 


The SCREENGROUP structure contains information about the screen group. 


Fields idScreenGrp Specifies the screen-group identifier of the new foreground 
screen or for notification action. The identifier can range from zero to the max- 
imum number of screen groups. The sgMax field in the global descriptor table 
(GDT) information segment specifies the maximum number of screen groups. 


fTerminate Specifies if the screen group is terminating. If it is 0x0000, the 
screen group is switching. If it is OxFFFF, the screen group is terminating. 


See Also KBD_SETFGNDSCREENGRP, MOU_SCREENSWITCH 


SHIFTSTATE 
typedef struct _SHIFTSTATE { /* shftst */ 
USHORT fsState; 


. BYTE f£NLS; 
} SHIETSTATE ; 


The SHIFTSTATE structure contains information about the shift state of the 
default keyboard of the current screen group. 
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Fields fsState Specifies the state of the shift keys. It can be any combination of the 

following values: 
Value Meaning 
RIGHTSHIFT Right sHIFT key down. 
LEFTSHIFT Left SHIFT key down. 
CONTROL Either CONTROL key down. 
ALT Either ALT key down. 
SCROLLLOCK_ON SCROLL LOCK mode turned on. 
NUMLOCK_ON NUMLOCK mode turned on. 
CAPSLOCK_ON CAPSLOCK mode turned on. 
INSERT_ON INSERT mode turned on. 
LEFTCONTROL Left CONTROL key down. 
LEFTALT Left ALT key down. 
RIGHTCONTROL Right CONTROL key down. 
RIGHTALT Right ALT key down. 
SCROLLLOCK SCROLL LOCK key down. 
NUMLOCK NUMLOCK key down. 

~ CAPSLOCK CAPSLOCK key down. 

SYSREQ SYSREQ key down. 

fNLS Specifies the state of the national-language-support keys. This is zero for 

the United States. 

See Also KBD_GETSHIFTSTATE, KBD_SETSHIFTSTATE 


m™ STARTDATA 


typedef struct _STARTDATA { 


USHORT Length; 
USHORT Related; 
USHORT FgBg; 
USHORT TraceOpt; 
PSZ PgmTitle; 
PSZ PgmName; 


/* stdata */ 


PBYTE 
PBYTE 
PBYTE 
USHORT 
USHORT 
PSZ 
ULONG 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 


PgmInputs; 
TermQ; 
Environment; 
InheritOpt; 
SessionType; 
IconFile; 
PgmHandle; 
PgmControl; 
InitXPos; 
InitYPos; 
InitXSize; 
InitYSize; 


} STARTDATA; 


The STARTDATA structure contains information about a session that will be 
started with the DosStartSession function. 
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Fields 


STARTDATA 


Length Specifies the length of the structure (in bytes). It must be set to 50 
bytes. 


Related Specifies whether the session created is related to the calling session. 
If this field is FALSE, the new session is an independent session (not related). 
If it is TRUE, the new session is a child session (related). 


FgBg Specifies whether the new session is started in the foreground or in the 
background. If this field is TRUE, the session is started in the background. If it 
is FALSE, the session is started in the foreground. 


TraceOpt Specifies whether the program started in the new session is exe- 
cuted under conditions for tracing. If this field is 0, there is no tracing. If it is 1, 
there is tracing. 


PgmTitle Points to the null-terminated string that specifies the program title. 
The string can be up to 32 bytes long, including the null terminating character. If 
the address specified is zero or if the null-terminated string is NULL, the initial 
title is the value of the PgmName field minus any leading drive and path infor- 
mation. 


PgmName Points to the null-terminated string that specifies the drive, path, 
and filename of the program to be loaded. 


PgmInputs Points to the null-terminated string that specifies the input ae 
ments to be passed to the program. 


TermQ Points to the null-terminated string that specifies the full path name of 
an MS OS/2 queue or is equal to zero. This parameter is optional. 


Environment Points to an environment string that is to be passed to the pro- 
gram started in the new session. If this field is zero, the program in the new 
session inherits the environment of the parent session if the InheritOpt field 

is zero, or the environment of the program calling DosStartSession if the 
InheritOpt field is one. 


InheritOpt Specifies whether the program started in the new session inherits 
the environment and open file handles of the calling process. If this field is zero, 
inheritance is from the parent session. If this field is 1, inheritance is from the 
calling process. 


SessionType Specifies the type of session that should be created. It is one of 
the following values: 


Value Meaning 

0 Use the data specified by the PgmHandle field or allow MS 
OS/2 to establish the session type. 

1 Start the process in a full-screen session. 

Z Start the process in a window session for programs using the 


base video subsystem. 


3 Start the process in a window session for programs using the 
Presentation Manager application programming interface. 


IconFile Points to a null-terminated string that contains the fully-qualified 
device, path name, and filename of an icon definition. The system provides an 
icon for window applications if an icon filename is not provided a the 
DosStartSession call. 


PgmHandle ° Specifies a program handle. 


See Also 


™@ STATUSDATA 


STATUSDATA = 365 


PgmControl Specifies the initial state for a window application. This field is 
ignored by full-screen sessions. It can be any combination of the following 
values: 


Value Meaning 

0 Invisible 

2 Maximize 

4 Minimize 

8 No auto close 

32768 Use specified position and size 


InitXPos Specifies the initial x coordinate (in pels) for the initial-session win- 
dow, where (0,0) is the lower-left corner of the display. This field is ignored for 
full-screen sessions. 


InitYPos Specifies the initial y coordinate (in pels) for the initial-session win- 
dow, where (0,0) is the lower-left corner of the display. This field is ignored for 
full-screen sessions. 


InitXSize Specifies the width (in pels) for the initial-session window. This 
field is ignored for full-screen sessions. 


InitYSize Specifies the height (in pels) for the initial-session window. This 
field is ignored for full-screen sessions. 


DosStartSession 


Fields 


typedef struct _STATUSDATA { /* stsdata */ 
USHORT Length; 
USHORT Selectind; 
USHORT BindInd; 

} STATUSDATA; 


The STATUSDATA structure contains status information about a session. 


Length Specifies the length of the data structure (in bytes). 


SelectInd Specifies whether the target session should be set as selectable or 
nonselectable. It can be one of the following values: 


Value Meaning 
TARGET_UNCHANGED Leave current setting unchanged. 
TARGET_SELECTABLE Set as selectable. 


TARGET_NOT_SELECTABLE Set as nonselectable. 


BindInd Specifies which session to bring to the foreground the next time the 
parent session is selected. It can be one of the following values: 


Value Meaning 
BIND_UNCHANGED Leave current setting unchanged. 
BIND_CHILD A bond between the parent session and the 


child session is established. The child session is 
brought to the foreground the next time the 


366 STATUSDATA 


Value Meaning 


parent session is selected. If the child sessi 
selected, the child session is brought to the fore- 
ground. 


BIND_NONE Any bond previously established with the speci- 
fied child session is broken. The parent session 
is brought to the foreground the next time the 
parent session is selected and the child session 
is brought to the foreground the next time the 
child session is selected. 


See Also DosSetSession 
STRINGINBUF 
typedef struct _STRINGINBUE { /* kbsi */ 
USHORT cb; 
USHORT cchIn; 
} STRINGINBUE ; 
The STRINGINBUF structure contains information about the length of the buffer 
used by the KbdStringIn function. 
Fields cb Specifies the length of the buffer (in bytes). The maximum value is OxO0OFF. 
cchIn Specifies the number of bytes read. The maximum value is OxOOFF. 
See Also KbdStringIn . 
TRACKFORMAT 
typedef struct _TRACKFORMAT { /* trekfmt */ 
BYTE bCommand; 
USHORT usHead; 
USHORT usCylinder ; 
USHORT usReserved; 
USHORT cSectors; 
struct { 
BYTE bCylinder; 
BYTE bHead; 
BYTE idSector; 
BYTE bBytesSector; 
} FormatTable[1]; 
} TRACKFORMAT; 
The TRACKFORMAT structure contains information about the disk drive. 
Fields bCommand _ Specifies the type of track layout. If this field is Ox0000, the track. 


layout contains nonconsecutive sectors or does not start with sector 1. If it is 
0x0001, the track layout starts with sector 1 and contains only consecutive sec- 
tors. 


usHead Specifies the number of the physical head on which to perform the 
operation. 


usCylinder Specifies the cylinder number for the operation. 
cSectors Specifies the number of sectors on the track being formatted. 


See Also 


m@ TRACKLAYOUT 


TRACKLAYOUT = 367 


FormatTable[1] Specifies the format table. It is an array of structures that 
contain the cylinder number, head number, sector identifier, and bytes per sec- 
tor for each sector on the track. The bCylinder field specifies the cylinder 
number. The bHead field specifies the head number. The idSector field specifies 
the sector identifier, and the bBytesSector field specifies the number of bytes per 
sector. The first element defines these values for the first sector. The number of 
elements depends on the number of sectors on the track. The bBytesSector field 
can be one of the following values: 


Value Meaning 

0x0000 128 bytes per sector 
0x0001 256 bytes per sector 
0x0002 512 bytes. per sector 
0x0003 1024 bytes per sector 


All the cylinder and head numbers must be the same. 


DSK_FORMATVERIFY 


Fields 


typedef struct _TRACKLAYOUT { /* trekl */ 
BYTE bCommand; 
USHORT usHead; 
USHORT usCylinder; 
USHORT usFirstSector; 
USHORT cSectors; 
struct { 
USHORT usSectorNumber ; 
USHORT usSectorSize; 
} TrackTable[1}; 
} TRACKLAYOUT; 


-The TRACKLAYOUT structure contains track-layout information. 


bCommand Specifies the type of track layout. If this field is 0x0000, the track 
layout contains nonconsecutive sectors or does not start with sector 1. If it is 
0x0001, the track layout starts with sector 1, and contains only consecutive sec- 
tors. 


usHead Specifies the physical head on the disk drive on which to perform the 
operation. 


usCylinder Specifies the cylinder number on which to perform the operation. 


usFirstSector Specifies the logical sector number at which to start the opera- 
tion. The logical sector number is the index in the track-layout table to the first 
sector. Index 0 specifies the first sector, index 1 the second, and so on. 


cSectors Specifies the number of sectors on which to perform the operation, 
up to the maximum specified in the track-layout table. The function does not 
step heads and tracks. 


TrackTable[1] Specifies the track-layout table. It is an array of structures 
that contain the numbers and sizes of the sectors in the track. The first element 
in this field defines the sector number and size (in bytes) of the first sector on 
the track, the second element defines the second sector, and so on. For each 
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See Also 


element of TrackTable, the usSectorNumber field specifies the sector number, 
and the usSectorSize field specifies the size of the sector. The number of ele- 
ments depends on the number of sectors on the track. 


PDSK_READPHYSTRACK, DSK_READTRACK, 
PDSK_VERIFYPHYSTRACK, DSK_VERIFYTRACK, 
DSK_WRITETRACK, PDSK_WRITEPHYSTRACK 


@ VIOCONFIGINFO 


Fields 


See Also 


- typedef struct _VIOCONFIGINFO { 


USHORT cb; 

USHORT adapter; 

USHORT display; 

ULONG cbhMemory; 
} VIOCONFIGINFO; 


/* vioin */ 


The VIOCONFIGINFO structure contains configuration information about the 


screen. 


cb = Specifies the length of the structure (in bytes). This field must be set to 10 
before calling the VioGetConfig function. 


adapter Specifies the display-adapter type. It can be one of the following 


values: 
Value 
DISPLAY_MONOCHROME 
DISPLAY_CGA 
DISPLAY_EGA 
DISPLAY_VGA 


DISPLAY_8514A 


Monochrome/printer adapter 
Color graphics adapter 
Enhanced graphics adapter 


Video graphics array or IBM Personal 
System/2 display adapter 


PS/2 Display adapter 8514/A 


display Specifies the display/monitor type. It can be one of the following 


values: 
Value 


MONITOR_MONOCHROME 
MONITOR_COLOR 
MONITOR_ENHANCED 
MONITOR_ 8503 
-MONITOR_851X_COLOR 
MONITOR.8514 


Meaning 


Monochrome display 
Color display 

Enhanced color display 
8503 monochrome display 
8512 or 8513 color display 
8514 color display 


cbMemory Specifies the amount of memory on the adapter (in bytes). 


VioGetConfig 


VIOFONTINFO 369 


— VIOCURSORINFO 


typedef struct _VIOCURSORINFO { /* vioci */ 
USHORT yStart; 
USHORT cEnd; 
USHORT cx; 
USHORT attr; 
} VIOCURSORINEO; 


The VIOCURSORINFO structure contains information about the cursor. 


Fields yStart Specifies the horizontal scan line that marks the top line of the cursor. 
Scan lines are numbered from 0 to n-1, where n is the maximum height of a 
character cell. Scan line 0 is at the top of the character cell. 


cEnd = Specifies the horizontal scan line that marks the bottom line of the cur- 
sor. 


cx Specifies the width of the cursor in columns (for text mode) or in pels (for 
graphics mode). The maximum width in text mode is 1. If zero is given, the 
function uses a default width: 1 for text mode or the width of a character cell for 
graphics mode. 


attr Specifies the attribute of the cursor. If this field is OxFFFF, the function 
hides the cursor (removes it from the screen). Any other value sets the current 
character attribute of the cursor. 


See Also VioGetCurType, VioSetCurType 


m@ VIOFONTINFO 


typedef struct _VIOFONTINFO { /* viofi */ 
USHORT cb; 
USHORT type; 
USHORT cxCell; 
USHORT cyCell; 
PVOID pbData; 
USHORT cbData; 
} VIOFONTINEO; 


The VIOFONTINFO structure contains information about the font. 


Fields cb Specifies the length of the structure (in bytes). It must be set to 14. 


type Specifies the request type. This field must be VGFILGETCURFONT to 
retrieve the current font. It must bb VGFILGETROMFONT to retrieve a ROM 
font. It must be 0x0000 to set a font. 


exCell Specifies the width (in pels) of each character cell in the font. 
cyCell Specifies the height (in pels) of each character cell in the font. 


pbData Points to the buffer that receives the requested font table or can be 
set to NULL to direct the VioGetFont function to supply an address. In the 
latter case, the function copies the address of the font to this field. The address 
specifies either a RAM or a ROM address, depending on the request type. 


For the VioSetFont function, it points to the buffer that contains the font table 
to set a font. The format of the font table depends on the display adapter and 
screen mode. 


cbData Specifies the length of the font (in bytes). 
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Comments . When requesting a ROM font, the exCell and cyCell fields must be set before 
calling the VioGetFont function. These fields identify the font to be retrieved. 


See Also VioGetFont, VioSetFont 


VIOINTENSITY 


typedef struct _VIOINTENSITY { /* vioint */ 
USHORT cb; 
USHORT type; 
USHORT fs; 

} VIOINTENSITY; 


The VIOINTENSITY structure contains status information about foreground and 
background color. . 
Fields cb Specifies the length of the structure (in bytes). It must be set to 6. 


type Specifies the request type. To retrieve the blink/background intensity 
switch, this field must be set to 0x0002. 


fs Specifies foreground and background color status. This field must be set to 
0x0000 for blinking foreground colors, or 0x0001 for high-intensity background 


colors. 
See Also VioGetState, VioSetState, VIOOVERSCAN, VIOPALSTATE 
VIOMODEINFO 
typedef struct _VIOMODEINFO { /* viomi */ 
USHORT cb; 


UCHAR fbType; 
UCHAR’ color; 
USHORT col; 
USHORT row; 
USHORT hres; 
USHORT vres; 

} VIOMODEINEO; 


The VIOMODEINFO structure contains information about the screen mode. 


Fields cb = Specifies the length of the data structure (in bytes). This field must be set 
to 12. 
fbType Specifies the screen mode. It is one of the following values: 
Value Meaning 


VGMT_OTHER Set adapter to other than a monochrome/printer 
adapter. If this value is not given, the | 
monochrome/printer adapter is assumed by 
default. 


VGMT_GRAPHICS Set graphics mode. If this value is not given, the 
adapter is set to text mode. 


VGMT_DISABLEBURST Disable color-burst mode. If this value is not 
given, color-burst mode is enabled. 
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color Specifies the number of colors (defined as a power of 2). This is 
equivalent to the number of color bits that define the color. It is one of the 
following values: 


Value Meaning 
COLORS_2 2 colors 
COLORS_4 4 colors 
COLORS_16 = 16 colors 
col Specifies the number of text columns. 
row Specifies the number of text rows. 
hres Specifies the number of pel columns (horizontal resolution). 
vres Specifies the number of pel rows (vertical resolution). 


See Also VioGetMode, VioSetMode 
VIOOVERSCAN 
typedef struct _VIOOVERSCAN { f* vioos */ 
USHORT cb; 


USHORT type; 
USHORT color; 
} VIOOVERSCAN; 


The VIOOVERSCAN structure contains the overscan (border) screen color. 


Fields cb Specifies the length of the structure (in bytes). It must be set to 6. 


type Specifies the request type. To retrieve the overscan (border) color, this 
field must be set to 0x0001. 


color Specifies the color value. 


See Also VioGetState, VioSetState, VIOINTENSITY, VIOPALSTATE 


VIOPALSTATE 
typedef struct _VIOPALSTATE { /* viopal */ 
USHORT cb; 


USHORT type; 

USHORT iFirst; 

USHORT acolor [1]; 
} VIOPALSTATE ; 


The VIOPALSTATE structure contains the screen-palette registers. 


Fields cb Specifies the length of the structure (in bytes). The length determines how 
many palette registers are retrieved. The maximum length is 38 bytes for 16 
registers. 


type Specifies the request type. To retrieve the palette register state, this field 
must be set to 0x0000. 


_ See Also 


VIOPHYSBUF 


Fields 


Comments 


See Also 


VOLUMELABEL 
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iFirst Specifies the first palette register to be retrieved. This field must be a 
value from 0x0000 to 0x000F. The function retrieves the palette registers in 


garmwastial ~wnAne cae ay See i aaa 


sequcentia: oraer. The number of registers retrieved depends on the structure size 


specified by the cb field. 


acolor[1] Specifies the array that receives the color values for the palette 
registers. 


VioGetState, VioSetState, VIOINTENSITY, VIOOVERSCAN 


typedef struct _VIOPHYSBUF { /* viopb */ 
PBYTE pBuf; 
ULONG cb; 
SEL asel[1]; 

} VIOPHYSBUE ; 


The VIOPHYSBUF structure contains information about the physical video 
buffer. 


pBuf Points to the physical video buffer. The address must be in the range 
0x000A.0000 through OxOOOBFFFF; this depends on the display adapter and the 
video mode. 


cb — Specifies the length of the physical video buffer (in bytes). 


asel[1] Specifies the array that receives the selectors used to address the 
physical video buffer. If more than one selector is received, the first selector 
addresses the first 64K bytes of the physical video buffer, the second selector 
addresses the next 64K bytes, and so on. The number of selectors depends on 
the actual size of the physical buffer as specified by the cb field. The last selector 
may address less than 64K bytes of buffer. 


The actual size of the asel[1] field depends on the size of physical memory. The 
program must ensure that there is adequate space to receive all selectors. 


VioGetPhysBuf 


Fields 


See Also 


typedef struct _VOLUMELABEL { /* vol */ 
BYTE cch; 
CHAR szVolLabel [12]; 

} VOLUMELABEL; 


The VOLUMELABEL structure contains the volume label. 


cch Specifies the length of the achVolLabel[12] field (excluding the null- 
terminating character). 


achVolLabel[12] Specifies a null-terminated string that specifies the volume 
label. When a volume label is being set by using the DosSetFSInfo function, any 
trailing spaces are ignored. 


DosQFSInfo, DosSetFSInfo 
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5.1 Introduction 


This chapter describes the format of the files and related structures used by 
MS OS/2 functions. The following topics are described in detail: 


® Keyboard translation tables 
H Video fonts 
™@ Resources 


This chapter describes the formats as returned by or required by the MS OS/2 
functions that use them. The formats described here may not fully describe the 
format of data when it is stored in an MS OS/2 system file. For example, the 
system default keyboard translation tables are stored in the keyboard.dcp file. 
This file usually contains header information and several translation tables. 
Although the translation-table format is described in this chapter, the header 
information and the organization of the tables in the files are not. 


In general, this chapter describes only the details needed to develop data for- 
mats for use with MS OS/2 programs. The programmer can choose an appro- 
priate file-storage format. 


5.2 Keyboard Translation Tables 


This section describes the format and contents of MS OS/2 translation tables. 
MS OS/2 uses translation tables to translate keystroke scan codes into character 
values. 


5.2.1 Predefined Translation Tables 


MS OS/2 provides several predefined translation tables. These tables, defined in 
the keyboard.dcp file, specify the translations for keyboard scan codes to charac- 
ter values for a variety of character sets and languages. Each translation table is 
identified by a code-page identifier. The code-page ID may be used in the Dos- 
SetCp, KbdSetCp, and VioSetCp functions to set the translation table for the 
system. The DosGetCp, KbdGetCp, and VioGetCp functions also retrieve the 
code-page ID for the current system translation table. 


The following is a list of the MS OS/2 predefined translation tables and their 
code-page identifiers: 


Number Code page 

437 United States 
850 Multilingual 

860 Portuguese 

863 French-Canadian 
865 Nordic 


0x0000 Default (none) 
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A user can set the translation tables for the system by using the codepage and 


a 
devinfo commands in the config.sys file. The keyb command can be used to 
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change the current translation table. 


5.2.2 Translation-Table Format 


MS OS/2 lets a program create and set custom translation tables for the key- 
board by using the KbdSetCustXt function. The function takes a pointer to 
translation table. The translation table is a structure that has the following 
general form: 


Translation-table header 
Key-definition 1 
Key-definition 2 


Key-definition 127 
Accent-key table 


The translation-table header defines the translation table’s code-page ID, the 
size of the translation table, the keyboard for which it was designed, and other 
information about the translation table. The key-definition entries define key- 
translation type, the accent keys that can be used in combination with this key, 
and the actual translated character values. A translation table may have up 

to 127 key-definition entries. The accent-table entry defines the scan- and 
character-code translations for accent-and-character key combinations. This 
accent table contains seven accent entries and accent-key definitions. 


struct { 

USHORT XTableID; 

USHORT XTableFlags1; 

USHORT XTableFlags2; 

USHORT KbdType; 

USHORT KbdSubType; 

USHORT XTableLen; 

USHORT EntryCount; 

USHORT EntryWidth; 

USHORT Country; 

USHORT TableTypeID; 

USHORT Reserved([10]; 

struct { 
USHORT AccentFlags:7; 
USHORT KeyType:9; 
CHAR Chari; 
CHAR Char2; 
CHAR Char3; 
CHAR Char4; 
CHAR CharS5; 

} KeyDef [127]; 

struct { 
BYTE NonAccent [2]; 
BYTE CtlAccent [2]; 
BYTE AltAccent [2]; 
BYTE Map[20] [2]; 

} AccentEntry([7]; 
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Field Description 

XTableID Specifies the code-page ID for this translation. 

XTableFlags1 Specifies the first set of table flags. For more 
information, see the values listed in Table 5.1. 

XTableFlags2 Specifies a reserved value; must be zero. 

KbdType Specifies the keyboard type. This field is 0x0000 
for an IBM PC/AT keyboard and 0x0001 for an 
IBM Enhanced keyboard. 

KbdSubType Specifies a reserved value; must be zero. 

XTableLen Specifies the length of the translation table 
(in bytes). 

EntryCount Specifies the number of key-definition entries. 

Entry Width Specifies the width of each key-definition entry 
(in bytes). 

Country Specifies the country-code or language ID. This 
ID consists of two letters that represent the name 
of a country. The first letter is stored in the high- 
order byte, the second in the low-order byte. 
For more information, see the codes listed in 
Table 5.2. 

TableTypeID Specifies the table type. The low-order byte 
specifies the type, the high-order byte the sub- 
type. This field must be 0x0001. 

Reserved([10] Specifies an array of reserved values. Each ele- 
ment must be zero. ’ 

AccentFlags Specifies the translation for accent keys. This 
field occupies bits 0 through 6. 

KeyType Specifies the translation of the keys. This field 
occupies bits 11 through 15. 

Charl Specifies a translated-character value. Typically 
used when no shift keys are pressed. 

Char2 Specifies a translated-character value. Typically 
used when shift keys are pressed. 

Char3 Specifies a translated-character value. Typically 
used when the ALT GR (alternate-graphics) key is 
pressed. 

Char4 Specifies a translated-character value. 

Char5 Specifies a translated-character value. 
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Field Description 


NonAccent[2] Specifies the character value and scan code for 
the key when not used as an accent character. 
The first byte contains the character value, the 
second the scan code. 


CtlAccent[2] Specifies the character value and scan code for 
. ae the key when used with the CONTROL key. The 
first byte contains the character value, the second 
the scan code. 


AltAccent[2] Specifies the character value and scan code for 
the key when used with the ALT key. The first 
byte contains the character value, the second the 
scan code. 


Map[20] [2] Specifies an array of scan-code and character- 
value pairs for accented translation. The array 
has 20 elements. Each element has two bytes; the 
first byte contains the scan code of a key to be 
accented and the second contains the character 
value of the accented key. 


The XTableFlags1 field can be any combination of the values listed in Table 5.1: 
Table 5.1 Table-Flag Values 


Value Meaning 

0x0001 SHIFT+ALT is used in place of CONTROL+ALT. 

0x0002 Left ALT key is the ALT GR (alternate-graphics) key. 
0x0004 Right ALT key is the ALT GR (alternate-graphics) key. 
0x0008 CAPSLOCK key is interpreted as a SHIFTLOCK key. 
0x0010 Default table for the language. Used by the keyb com- 


mand to locate the default translation table if switch- 
ing between several translation tables. 


0x0020 SHIFTLOCK key is a toggle key. If not given, the key is 
a latch key. . 

0x0040 Accent is sent as a character. If not valid, beep is 
sounded. 

0x0080 When the CAPSLOCK is down and the SHIFT key is 


pressed, the CharS field is used in the key-definition 
entry. 
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The Country field specifies the country or language identifier. It can be any of 
the codes listed in Table 5.2: 


Table 5.2 Country and Language Codes 


Code 


US 
UK 
GR 
FR 
IT 
SP 
DK 
NL 
SU 
NO 
PO 
SV 
SF 
SG 
CF 
BE 
LA 


Country/Language 


United States 
United Kingdom 
Germany 
France 
Italy 
Spain 
Denmark 
' Netherlands 
Finland 
Norway 
Portugal 
Sweden 
Switzerland (French) 
Switzerland (German) 
French-Canadian 
Belgium 
Latin America (Spanish) 


Note that each accent entry should have the space character defined as one of its 
accented characters and be translated to the same value as the accent character 


itself. The 


reason for this is that, by definition, an accent key followed by the 


space character maps to the accent character alone. If the table is not set up this 
way, a “not-an-accent” beep sounds when the accent key, followed by a space, is 


pressed. 


5.2.3 Key Types 


The KeyType field specifies whether the scan code represents an alphabetic, spe- 
cial, function, shift, or other type of key. It also defines how to translate the key 


when a giv 
values: 


Value 

0x0001 
0x0002 
0x0003 


en shift key is down or active. This field can be one of the following 


Meaning 


Alphabetic-character key 
Special nonalphabetic-character key 


Special nonalphabetic-character key with CAPSLOCK 
translation 
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Value Meaning 

0x0004 Special nonalphabetic-character key with ALT translation 

0x0005 Special nonalphabetic-character key with CAPSLOCK and 
ALT translations 

0x0006 Function key 

0x0007 Keypad key 

0x0008 Action key that performs a special action when the 
CONTROL key is pressed 

0x0009 PRINTSCREEN key 

0x000A. SYSREQ key 

0x000B Accent key (also called a dead key) 

0x000C Shift key (for example, SHIFT or CONTROL) 

0x000D General toggle key 

0x000E ALT key 

0x000F NUMLOCK key 

0x0010 CAPSLOCK key 

0x0011 SCROLL LOCK key 

0x0012 Extended-shift key 

0x0013 Extended-toggle key 

0x0014 Special character key with CAPSLOCK translations for 


foreign-language keyboards 


0x0015 Special character key with ALT translations for foreign- 
. language keyboards . 


The AccentFlags field of a key-definition entry has seven flags that are individ- 
ually set if a corresponding entry in the accent table applies to this scan code. 
If an accent key is pressed immediately before the current key, and if the 

bit for that accent key is set in the AccentFlags field for the current key, the 
corresponding accent-table entry is searched for the replacement character 
value. If no replacement is found, the “not-an-accent” beep sounds and the 
accent character and current character are passed as two separate characters. 


The SPACEBAR should have a flag set in its AccentFlags field for each possible 
accent (that is, for each defined accent entry in the accent table). 


When no shift keys are pressed, the Charl field specifies the translated-character 
value (except where otherwise noted). 


The ALT key, the ALT-GR key, or both, may be present on a keyboard as speci- 
fied by the XTableFlags1 field in the translation-table header. In most cases, 

if the ALT GR key is specified, the Char3 field specifies the translated-character 
value when the given key is pressed at the same time as the ALT key. 
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Any key combination that does not have an explicit definition is assumed to be 
undefined—for example, pressing the CONTROL key with the 3 key. The system 
marks the keystroke packet as an undefined translation and passes the packet on 
to any keyboard monitors. The scan code in the packet remains unchanged but 
the character value is set to zero. Although the system passes the packet to mon- 
itors, it does not copy the undefined translation to the keyboard-input buffer. 


The system uses the masks listed in Table 5.3 to set and clear the keyboard 


shift-status word: 
Table 5.3 Shift-Key Masks 
Key 


SHIFT (right) 
SHIFT (left) 
CONTROL+SHIFT 
ALT+SHIFT 
SCROLL LOCK 
NUMLOCK 
CAPSLOCK 


SYSREQ 


Char1 Char2 Char3 
0x01 0x00 0x00 
0x02 0x00 0x00 
Ox04 Ox01 0x04 
0x08 0x02 0x08 
0x10 0x10 0x10 
0x20 0x20 0x20 
0x40 0x40 0x40 
0x80 0x80 - 


The following sections describe the key types in detail. 


5.2.3.1 Alphabetic Key (Type 0x0001) 
An alphabetic key (type 0x0001) is any character key that represents a letter. 


Shift key 


None 
SHIFT 
CAPSLOCK 


SHIFT and 
CAPSLOCK 


CONTROL 
ALT 
ALT GR 


Field used 


Charl 
Char2 
Char2 


Charl 

Char1 to compute an ASCII control value. 

Chari to compute an IBM PC keyboard scan code. 
Char3 if this field is not zero. 


If a CONTROL key is pressed, the system subtracts 95 from the Charl field to 
compute an ASCII control value. The final value ranges from 1 through 26. 
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of IBM PC keyboard scan codes. The final value is two bytes. The first byt 


0x00. The second byte is the corresponding IBM PC scan code. 
5.2.3.2 Special-Character Key (Type 0x0002) 


A special-character key (type 0x0002) represents a nonalphabetic character for 
which there is no CAPSLOCK or ALT translation. 


Shift key Field used 

None Chari 

SHIFT Char2 

CAPSLOCK Charl 

CONTROL Computed ASCII control code. 
ALT Undefined translation. 

ALT GR Char3 if this field is not zero. 


If a CONTROL key is pressed, the system uses the scan code of the given key to 
generate an ASCII control code, as shown in the following list: 


Scan code Control code 
0x03 0x00 
0x07 0x1E 
0x0C Ox1F 
Ox1A 0x1B 
0x1B 0x1D 
0x2B Ox1C 


Only the scan codes listed generate control codes. A hyphen-character (—) key 
always generates control code Ox1F, even if the corresponding scan code is not 
listed. A hyphen-character key is any key whose Char1 field is 0x2D. 


§.2.3.3 Special-Character Key (Type 0x0003) 


A special-character key (type 0x0003) represents a nonalphabetic character for _ 
which there is a CAPSLOCK translation but no ALT translation. 


Shift key Field used 
None Chari 
SHIFT Char2 
CAPSLOCK Char2 
SHIFT and 

CAPSLOCK Charli 


CONTROL Computed ASCTI control code. 
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Shift key Field used 
ALT Undefined translation. 
ALT GR Char3 if this field is not zero. 


If a CONTROL key is pressed, the system uses the scan code of the given key to 
generate an ASCII control code, as shown in the following list: 


Scan code Control code 
0x03 0x00 
0x07 Ox1E 
0x0C Ox1F 
Ox1A 0x1B 
0x1B 0x1D 
0x2B Ox1C 


Only the scan codes listed generate control codes. A hyphen-character (-) key 
always generates control code Ox1F, even if the corresponding scan code is not 
listed. A hyphen-character key is any key whose Char1 field is 0x2D. 


5.2.3.4 Special-Character Key (Type 0x0004) 


A special-character key (type 0x0004) represents a nonalphabetic, non-action key 
for which there is an ALT translation but no CAPSLOCK translation. Typically, 


these keys represent numeric and punctuation characters. The SPACEBAR key is 
also a type 0x0004 key. 


Shift key Field used 

None Charl 

SHIFT Char2 

CAPSLOCK Charl 

CONTROL Computed ASCII control code. 
ALT Computed extended ASCII code. 
ALT GR Char3 if this field is not zero. 


If a CONTROL key is pressed, the system uses the scan code of the given key to 
generate an ASCII control code, as shown in the following list: 


Sean code Control code 
0x03 0x00 
0x07 0x1E 
0x0C Ox1F 


Ox1A 0x1B 
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Scan code Control code 


0x1B 0x1D 
0x2B 0x1C 


Only the scan codes listed generate control codes. A hyphen-character (-) key 
always generates control code Ox1F, even if the corresponding scan code is not 
listed. A hyphen-character key is any key whose Charl field is 0x2D. Both the 
ALT+SPACEBAR and CONTROL+SPACEBAR combinations generate the ASCII 
space character. 


If the ALT key is pressed, the system uses the scan code of the given key to gen- 
erate an extended ASCII code, as shown in the following list: 


Scan code Control code 
0x02 0x78 
0x03 0x79 
0x04 Ox7A 
0x05 — 0x7B 
0x06 0x7C 
0x07 0x7D 
0x08 Ox7E 
0x09 Ox7F 
Ox0A. 0x80 
0x0B 0x81 
0x0C 0x82 
0x0D 0x83 


The final value is two bytes. The first byte is 0x00 or OxEO. The second byte is 
the corresponding extended ASCII code. 


§.2.3.5 Special-Character Key (Type 0x0005) 


A special-character key (type 0x0005) represents a nonalphabetic character that 
has both CAPSLOCK and ALT translations. 


Shift key Field used 
None Charl. 
SHIFT Char2 
CAPSLOCK Char2 
SHIFT and 

CAPSLOCK Charl 


CONTROL Computed ASCII control code. 
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Shift key Field used 


ALT Computed extended ASCII code. 
ALT GR Char3 if this field is not zero. 


Only the scan codes listed generate control codes. A hyphen-character (-) key 
always generates control code Ox1F, even if the corresponding scan code is not 
listed. A hyphen-character key is any key whose Charl field is Ox2D.  - 


If the ALT key is pressed, the system uses the scan code of the given key to gen- 
erate an extended ASCII code, as shown in the following list: 


Scan code Control code 
0x02 0x78 
0x03 0x79 
0x04 Ox7A 
0x05 0x7B 
0x06 Ox7C 
0x07 0x7D 
0x08 Ox7E 
0x09 Ox7F 
Ox0A 0x80 
0x0B 0x81 
0x0C 0x82 
0x0D 0x83 


The final value is two bytes. The first byte is 0x00 or OxE0. The second byte is 
the corresponding extended ASCII code. 


5.2.3.6 Function Key (Type 0x0006) 


A function key (type 0x0006) represents a non-ASCII key that may be used to 
direct an action. The system uses the Charl field to generate an extended ASCII 
code for the given key. The Chari field should be set to the same value as the 
key—for example, 1 for the Fi key, 2 for the F2 key, and so on. The system gen- 
erates the extended ASCIT code by adding a value to Char1, as shown in the fol- 
lowing list: ie : . 


Shift key Extended code 


None Adds 0x3A to Charl. The F1i and F12 keys are 
always Ox8B.and Ox8C, respectively. 


SHIFT Adds 0x53 to Charl. The SHIFT+F11 and SHIFT+F12 
keys are always 0x8D and Ox8E, respectively. 
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Shift key Extended code 

CAPSLOCK Same as no shift key. 

CONTROL Adds 0x5D to Charl. The CONTROL+F11 and 
CONTROL+F12 keys are always Ox8F and 0x90, 
respectively. 

ALT Adds 0x67 to Charl. The ALT+F11 and ALT+F12 
keys are always 0x91 and 0x92, respectively. 

ALT GR Char3 if this field is not zero. 


5.2.3.7 Keypad Key (Type 0x0007) 


A keypad key (type 0x0007) represents a keypad character such as a direction or 


a numeric key. 


Shift key 


None 
SHIFT 
NUMLOCK 


SHIFT and 
NUMLOCK 


CAPSLOCK 
CONTROL 
ALT 

ALT GR 


The following list shows 
Key-top label 


HOME/7 
uP/8 
PAGE UP/9 
LEFT/4 

5 

RIGHT/6 

~. 

END/1 
DOWN/2 


Field used 


Char! used to compute an extended ASCII code. 
Char2 
Char2 


Same as no shift key. 

Same as no shift key. 

Special keypad codes. 

Build a character. 

Char3 if this field is not zero. 


the required Char1 values based on the key-top labels: 


Char1 value 


0x00 
0x01 
0x02 
0x03 
0x04 
0x05 
0x06 
0x07 
0x08 
0x09 
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Key-top label _ Chart value 
PAGE DOWN/3 0x0A 
INS/O 0x0B 
DEL/. Ox0C 


The Char2 value should represent the ASCII equivalent of the key-top label. 
For example, Char2 for the HOME/7 key should be the ASCII character 7. 


When the system generates an extended ASCII code, it creates two bytes. The 
first byte is 0x00 or OxEO. The second byte is a scan code equal to the Char1 
field plus 0x47. The plus (+) and minus (-) keypad keys never generate extended 
ASCII values; they always return the Char2 field. 


If the ALT key is pressed and held down, the system builds a character value by 
accumulating keystrokes. For each keystroke, the system multiplies the accumu- 
lated value by 10, then adds the decimal value of the given key. For example, 
pressing the HOME/7 key adds 7 to the accumulated value. If the result is greater 
than 255, the high bits are truncated. If any key other than the numeric keys is 
pressed, the accumulated value is reset to zero. When the ALT key is released, 
the accumulated value becomes the character value and the scan code is set to 
zero. 


If the CONTROL key is pressed, the system generates special extended ASCII 
codes for the keypad keys, as shown in the following list: 


Key-top label Extended code 
HOME/7 0x77 
uP/8 0x8D 
PAGE up/9 0x84 
_ Ox8E 
LEFT/4 0x73 
5 - Ox8F 
RIGHT/6 0x74 
+ 0x90 
END/1 0x75 
DOWN/2 0x91 
PAGE DOWN/3 0x76 
INs/0 0x92 


DEL/. 0x93 
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5.2.3.8 Special-Action Key (Type 0x0008) 


A special-action key (type 0x0008) represents an action key that carries out a 
special action when the CONTROL key is pressed. For example, the ENTER key 
generates the newline character in combination with the CONTROL key. When 
pressed alone, it generates the carriage-return character. The special action keys 
are given in the following list: 


Shift key Field used 

None Char1 

SHIFT Charl 

CAPSLOCK Charl 

CONTROL Char2 

ALT Undefined translation. 

ALT GR Char3 if this field is not zero. 


5.2.3.9 PRINTSCREEN Key (Type 0x0009) 


The PRINTSCREEN (print-screen) key (type 0x0009) directs the system to copy the 
screen contents to the printer. 


Shift key Field used 

None Charl 

SHIFT Directs the system to print the screen. 

CAPSLOCK Charl 

CONTROL Directs the system to echo each screen line to the 
printer. 

ALT Undefined translation. 

ALT GR Chars if this field is not zero. 


§.2.3.10 SYSREQ Key (Type Ox000A) 


The SYSTEQ (system-request) key (type 0x000A) represents a special shift key. 
The Charl field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
When the user presses this key, the system sets the shift-status word and clears 
it when the user releases the key. If a secondary-key prefix (OxE0) is received 
immediately prior to a shift key, the Char3 field is used in place of Char2 to set 
or clear the shift-status word. 
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§.2.3.11 Accent Key (Type 0x000B) 


An accent key (also called a dead key) (type 0x000B) represents a character that 
is combined with another character to form a new character. For example, an 
umlaut key can be combined with the letter u to form an umlaut-u character. 
The Charl, Char2, and Char3 fields are indexes into the translation table’s 
accent table. Each field must be a value from 1 through 7. 


Shift key Field used 
None Charl 

_ SHIFT Char2 
CAPSLOCK Charl 
CONTROL Chari, but use CtlAccent field in accent entry. 
ALT Charl, but use AltAccent field in accent entry. 
ALT GR Char3 


When an accent key is pressed with a CONTROL or ALT key, the system retrieves 
the character value from the CtlAccent[2] or AltAccent[2] field in the accent- 
table entry indexed by the Charl field. These fields contain the scan and charac- 
ter codes for the key. If the fields are both zero, the key has an undefined trans- 
lation. 


When an accent key is pressed by itself, the system uses the Charl field as an 
index to an accent-table entry. When an accent key is pressed with a SHIFT key, 
the system uses the Char2 field as an index to an accent-table entry. When an 
accent key is pressed with an ALT GR key, the system uses the Char3 field as an 
index to an accent-table entry. The system then waits for the next key. If the 
next key does not specify accent keys in the corresponding AccentFlags field or 
the next key is not found in the Map[20][2] field of the accent-table entry, then 
the character specified by the NonAccent field is used for the accent key and the 
second key is translated normally. Both characters are passed to the keyboard- 
input buffer after the “not-an-accent” beep sounds. 


If a key does not change when a left or right SHIFT key is held down, it should 
use the same value for Char1 and Char2 so that the accent will apply in both the 
shifted and non-shifted cases. If the accent value is undefined when used with a 
SHIFT key or with the ALT GR key, the value in Char2 or Char3 should be zero. 


If an accent key does not have ALT or CONTROL key mapping, the AltAccent and 
CtlAccent fields should be set to zero. 


5.2.3.12 Shift Key (Type 0x000C) 


A shift key (type 0x000C) represents a shift whose state changes when the key is 
pressed or released. The SHIFT and CONTROL keys are typical shift keys. 


The Charl field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
When the user presses the key, the system sets the shift-status word, and then 
clears it when the user releases the key. If a secondary-key prefix (OxE0) is 
received immediately prior to a shift key, the Char3 field is used in place of 
Char2 to set or clear the shift-status word. 
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§.2.3.13 General Toggle Key (Type 0x000D) 


A general toggle key (type 0x000D) represents a shift key whose state changes 
when the key is pressed but not when it is released. The CAPSLOCK key is a typi- 
cal toggle key. 


The Charl field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
The system uses Char1 to set the lower byte of the shift-status word when the 
user first presses the key. Thereafter the system alternates between setting and 
clearing on each subsequent press. The system uses Char2 to set the upper-byte 
word when the user presses the key and to clear it when the user releases the 
key. If a secondary-key prefix (OxE0) is received immediately prior to a toggle 
key, the Char3 field is used in place of Char2 to set or clear the shift-status 
word. 


§.2.3.14 ALT Key (Type Ox000E) 


The ALT key (type 0x000E) represents a special shift key that works in combina- 
tion with the keypad keys to build character values. The ALT key requires its 
own key type so that the system knows to clear the accumulated value when the 
user begins to build a character using the keypad. Otherwise, the system treats 
the ALT key the same as any other shift key. 


The Charl field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
When the user presses the key, the system sets the shift-status word and clears 
it when the user releases the key. If a secondary-key prefix (OxE0) is received 
immediately prior to a shift key, the Char3 field is used in place of Char2 to set 
or clear the shift-status word. 


If the XTableFlags1 field specifies an ALT GR key, the ALT key may be treated as 
that key. 


§.2.3.15 NUMLOCK Key (Type Ox000F) 


The NUMLOCK key (type Ox000F) represents a special toggle key that, when 
pressed in combination with the CONTROL key, directs the system to temporarily 
stop screen output. Otherwise, the system treats the NUMLOCK the same as any 
other toggle key. When CONTROL+NUMLOCK stops screen output, the next key- 
stroke (if it generates a valid character) restores output. 


The Charl field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
The system uses Charl to set the lower byte of the shift-status word when the 
user first presses the key. Thereafter the system alternates between setting and 
clearing on each press. The system uses Char2 to set the upper-byte word when 
the user presses the key and to clear it when the user releases the key. If a 
secondary-key prefix (OxEO) is received immediately prior to a toggle key, the 
Char3 field is used in place of Char2 to set or clear the shift-status word. 
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§.2.3.16 CAPSLOCK Key (Type 0x0010) 


The CAPSLOCK key (type 0x0010) represents a special toggle key. This key type 
only applies when the XTableFlags1 field specifies that the CAPSLOCK key is to 
be processed like a SHIFTLOCK key. When processed as a SHIFTLOCK key, the 

CAPSLOCK key sets the keyboard shift-status word but cannot be used to clear 

the word. To do this, a SHIFT key must be pressed. 


The Charl field holds a bit mask that the system uses to set the lower byte of 
the keyboard shift-status word. The Char2 field contains a bit mask that the sys- 
tem uses to set or clear the upper byte of the system’s shift-status word. The sys- 
tem uses Charl to set the lower byte of the shift-status word when the user first 
presses the key. Thereafter the system clears the byte only if the user presses a 
SHIFT key. The system uses Char2 to set the upper-byte word when the user 
presses the key and to clear it when the user releases the key. If a secondary-key 
prefix (OxE0) is received immediately prior to a toggle key, the Char3 field is 
used in place of Char2 to set or clear the shift-status word. 


§.2.3.17 SCROLL LOCK Key (Type 0x0011) 


The SCROLL LOCK key (type 0x0011) represents a special toggle key that gen- 
erates a CONTROL+BREAK signal for a program when it is pressed with the 
CONTROL key. Otherwise, the system treats the SCROLL LOCK key the same as 
any other toggle key. : 


The Charli field holds a bit mask that the system uses to set or clear the lower 
byte of the keyboard shift-status word. The Char2 field contains a bit mask that 
the system uses to set or clear the upper byte of the system’s shift-status word. 
The system uses Charl to set the lower byte of the shift-status word when the 
user first presses the key. Thereafter the system alternates between setting and 
clearing on each press. The system uses Char2 to set the upper-byte word when 
the user presses the key and to clear it when the user releases the key. If a 
secondary-key prefix (OxE0) is received immediately prior to a toggle key, the 
Char3 field is used in place of Char2 to set or clear the shift-status word. 


§.2.3.18 Extended-Shift Key (Type 0x0012) 


An extended-shift key (type 0x0012) represents a shift key that is used in con- 
junction with national-language support. The key is similar to the shift key 
(type 0x000C) but sets or clears the extra national-language-support byte of the 
keyboard-status word. 


The character fields are defined as follows: 


Field Description 


Charl Specifies the bit mask in which the bits that are on define 
the field used for the Char2 value. Only the bits in the 
national-language-support shift-status byte that corre- 
spond to the bits in this byte will be altered by the Char2 
value. 
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Field Description 


Char2 — Specifies the bit mask used to set or clear bits in the 
extended-status byte when the key is pressed or released. 


Char3 Specifies the replacement bit mask for Char2 when the 
secondary key prefix (OxE0) is recognized immediately 
prior to this key being pressed. 


Chari and Char2 can define single shift-status bits to set, clear, or toggle. Char2 
can be a set of coded bits (delineated by Char1) that will be set to a numeric 
value when the key is pressed and cleared to zero when released. When Charl 
has all bits on, the whole byte can be set to Char2. 


5.2.3.19 Extended-Toggle Key (Type 0x0013) 


An extended-toggle key (type 0x0013) represents a shift key that is used in con- 
junction with national-language support. The key is similar to the toggle key 
(type 0x000D) but it sets or clears the extra national-language-support byte of the 
keyboard-status word. 


The character fields are defined as follows: 
Field Description 


Charl Specifies the bit mask in which the bits that are on define 
the field used for the Char2 value. Only the bits in the 
national-language-support shift-status byte that corre- 
spond to the bits in this byte will be altered by the Char2 
value. 


Char2 _ Specifies the bit mask used to set or clear bits in the 
extended-status byte when the key is pressed. 


Char3 Specifies the replacement bit mask for Char2 when the 
secondary-key prefix (OxEO) is recognized immediately 
prior to this key being pressed. 


Char1 and Char2 can define single shift-status bits to set, clear, or toggle. Char2 
can be a set of coded bits (delineated by Char1) that will be set to a numeric 
value when the key is pressed and set to zero when released. When Char1 has 
all bits on, the whole byte can be set to Char2. 


5.2.3.20 Special Foreign Key (Type 0x0014) 


A special foreign key (type 0x0014) represents any character that may need a 
CAPSLOCK translation. 


Shift key Field used 
None Charl 
SHIFT Char2 


CAPSLOCK Char4 


ba 
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Shift key Field used 

CAPSLOCK 

and SHIFT Char5 

CONTROL Computed ASCII control value. 
ALT No effect. 

ALT-GR Char3 


5.2.3.21 Special Foreign Key (Type 0x0015) 


A special foreign key (type 0x0015) represents any character that may need an 
ALT translation. 


Shift key Field used 

None Charl 

SHIFT Char2 

CAPSLOCK No effect. 

CONTROL Computed ASCII control value. 
ALT Char4 

ALT-GR Char3 


When ALT or ALT+SHIFT is ae the scan code and translated character code 
are equal. 


5.3 Video Modes and Fonts 


5.3.1 Screen 


This section provides brief descriptions of the device-dependent values that may 
be used with the MS OS/2 video functions. In particular, it describes screen 
modes, screen attributes, video fonts, and physical-screen buffer addresses for 
the following display adapters: 


IBM Monochrome/Printer Adapter 

IBM Color Graphics Adapter (CGA) 
IBM Enhanced Graphics Adapter (EGA) 
IBM PS/2 Video Graphics Array (VGA) 
IBM PS/2 Display Adapter 


Modes 


The VioSetMode function sets the screen mode for the display adapter. The. 
screen mode defines the type of output (text or graphics) and the resolution of 
the output; that is, it defines the width and height of the screen in character cells 
or pels. The available screen modes depend on the display’s device driver as well 
as on the display adapter. Not all screen modes for a given display adapter are 
supported by the corresponding MS OS/2 display device driver. In general, an 
MS OS/2 display device driver supports at least one text mode and one graphics 
mode and, in many cases, the device driver supports all modes. 
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Tables 5.4 and 5.5 list the screen modes available for he IBM Monochrome/ 
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Graphics Array, PS/2 Display Adapter, and any nae that is one-hundred per- 
cent compatible with these. 


Table 5.4 Text Modes 


i . Cell 
Columns Rows Colors width 
80 25 2 9 
80 25 2 9 
40 25 16 8 
40 25 16 8 
40 25 16 9 
80 25 16 8 
80 25 16 8 
80 25 16 9 
Note 


Table 5.5 Graphics Modes 


Colors 


4 
2 


16 


Note 


Cell 
height 


14 
16 


Vertical 


Vertical 


resolution 


720 
720 
320 
320 


360 
640 


640 
720 


resolution 


320 


640 


320 


640 


640 


640 


640 
640 
320 


Horizontal 

resolution Display 

350 Monochrome/Printer Adapter 

400 VGA, PS/2 Display Adapter 

200 CGA,* EGA, VGA, PS/2 
Display Adapter 

350 EGA, VGA, and PS/2 
Display Adapter 

400 VGA, PS/2 Display Adapter 

200 CGA,* EGA, VGA, PS/2 
Display. Adapter 

350 EGA, VGA, PS/2 Display 
Adapter 

400 VGA, PS/2 Display Adapter 


* The color burst is turned off on the CGA. 


Horizontal 
resolution 


200 
200 
200 
200 
350 
350 


480 
480 
200 


* The color burst is turned off on the CGA. 


Display 
CGA,* EGA, VGA, and 
PS/2 Display Adapter 


CGA,* EGA, VGA, and 
PS/2 Display Adapter 


EGA, VGA, PS/2 Display 
Adapter 


EGA, VGA, PS/2 Display 
Adapter 


EGA, VGA, PS/2 Display 
Adapter 


EGA,** VGA, PS/2 Display 
Adapter 


VGA, PS/2 Display Adapter 
VGA, PS/2 Display Adapter 
VGA, PS/2 Display Adapter 


** Only 4 colors are available on an EGA configuration with less than 128K of video 


memory. 
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When the screen is in graphics mode, MS OS/2 supports only the following Vio 
functions: 


VioRegister 

VioDeRegister 

VioGetPhysBuf 

VioSavRedrawWait 
VioSavRedrawUndo 

VioScrLock 

VioScrUnLock 

VioPopUp 

VioEndPopUp 

VioModeWait 

VioModeUndo 

VioGetFont (request type 1 only) 
VioGetConfig 

VioSetState (request types 0 and 1 only) 
VioGetState (request types 0 and 1 only) 
VioSetMode 

VioGetMode 


5.3.2 Screen Attributes 


The screen attributes define the background and foreground colors and appear- 
ance of text when the screen is in text mode. A screen attribute is an 8-bit bit 
mask whose fields define the color and intensity of a character, as well as other 
attributes, such as underlining and blinking. The VioWrtCellStr, VioWrtChar- 
StrAtt, VioWrtNAttr, and VioWrtNCell functions use screen attributes as input 
parameters. The meaning of the fields within a screen-attribute bit mask depends 
on the display adapter. 


For the Monochrome/Printer Adapter, the screen attribute can be a combina- 
' tion of the following values: 


Value Meaning 

0x00 Blank character 

0x01 Underlined character 

0x07 Normal character 

0x08 High-intensity character 

0x70 Reverse-video character 

0x80 Blinking character or high-intensity background 


(depends on whether display-adapter blinker is active) 
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For the Color Graphics Adapter and the Enhanced Graphics Adapter, the 
screen attribute can be a combination of the following values: 


Value Meaning 
0x00 Black character 
0x01 Blue character 
0x02 Green character 
0x04 Red character 
0x08 High-intensity character 
0x10 Blue background 
0x20 Green background 
0x40 Red background 
0x80 Blinking character 


5.3.3 Physical-Screen Buffer Addresses 


The physical-screen buffer address is the starting address of the display adapter’s 
video-buffer memory. This starting address, as well as the size of the video 
memory and the format and meaning of the contents of the memory, depends on 
the display adapter and the screen mode. 


5.3.4 Video Fonts 


The VioGetFont and VioSetFont functions retrieve and set video fonts for the 
text-mode screen. These functions can be used with displays, such as the 
Enhanced Graphics Adapter and the Video Graphics Array, that accept down- 
loadable fonts. To use a custom font, a program can either create it or modify 
a copy of an existing font. A program uses the VioSetFont function to set 

the current font and the VioGetFont function to copy existing fonts from the 
display. 


For the Enhanced Graphics Maes and Video Graphics Array, a video font is 
an array of 256 character cells. Each cell consists of an array of scan-line data. — 
The cell height specifies number of scan lines for each cell. The width of the cell 
specifies the number of bytes for each scan line. Each bit represents a single pel 
in the character cell. If the bit is 1, the pel is the sks sea color. If the bit is 
0, the pel is the background color. 


Some VGA text modes specify character widths of 9 pels. The video fonts used 
with this mode supply only 8 bits. The display provides the additional back- 
ground pel automatically. 


5.4 Resource-File Formats 


An application can access the resources of an application c or dynamic-link library 
by using the DosGetResource function. MS OS/2 has several predefined 
resource formats that Presentation Manager applications can use to create 
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pointers, icons, bitmaps, menus, accelerator tables, and dialog windows. Other 
MS OS/2 programs can also access these resources directly, or they can define 
and access their own resources. The following is a list of the predefined resource 
formats: 


Resource type 


Resource format 


RT_POINTER Mouse-pointer shape 
RT_BITMAP Bitmap 

RT_MENU Menu template 
RT_DIALOG Dialog template 
RT_STRING String tables 
RT_FONTDIR Font directory 

RT_FONT Font 

RT_ACCELTABLE Accelerator tables 
RT_RCDATA Binary data 
RT_MESSAGE Error-message tables 
RT_DLGINCLUDE Dialog-include filename 
RT_VKEYTBL Scan-code to virtual-key tables 
RT_KEYTBL Key to font-glyph tables 
RT_CHARTBL Glyph to character tables 
RT_DISPLA YINFO Screen-display information 


Predefined resources such as pointers, dialog windows, and fonts can be created 
using Presentation Manager applications such as Icon Editor, Dialog Editor, and 
Font Editor. Other resources can be generated by using the MS OS/2 Resource 

Compiler (re). Resource Compiler also adds resources to the executable file for 

applications and dynamic-link libraries. 


Presentation Manager applications use the following functions to retrieve 
resources from an application’s executable file or a dynamic-link library. Some 
functions carry out additional steps, such as creating windows and bitmaps, and 
do not provide direct access to the data loaded. 

@ GpiLoadBitmap 

GpiLoadFonts 

WinLoadPointer 

WinLoadMenu 

WinLoadDlg 

WinLoadAccelTable 

WinLoadMessage 

WinLoadString 
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The following sections describe the internal format of the predefined resources. 
The format descriptions are useful for MS OS/2 programs that create new 
resources or that load these resources directly by using the DosGetResource 
function. 


5.4.1 Pointer and Icon Resources 


The RT_POINTER resource represents a pointer or icon resource. A pointer 
or icon resource is a special bitmap that contains two bit masks. Presentation 
Manager applications use the resource to draw mouse pointers or icons on the 
display. The WinLoadPointer function is typically used to load a pointer or icon 
resource and create a pointer handle. An application can draw the pointer or 
icon by passing the pointer handle to the WinDrawPointer function. 


The pointer and icon resources have the following format: 
/* These fields are identical to the BITMAPFILEHEADER structure. */ 


USHORT usType; /* PT for pointer or IC for icon */ 
ULONG cbSize; /* size of resource (in bytes) a/ 
USHORT xHotspot; /* x-coordinate of hot spot */ 
USHORT yHotspot; /* y-coordinate of hot spot */ 
ULONG offBits; /* offset to abANDMask array sd 


/* These fields are identical to the BITMAPINFOHEADER structure. */ 


ULONG cbhFix; /* size of BITMAPINFOHEADER structure */ 
USHORT cx; /* width of bitmap (in pels) & 

USHORT cy; /* height of bitmap (in pels) */ 
USHORT cPlanes; /* count of color planes in bitmaps */ 
USHORT cBitCount; /* count of bits per pel */ 


/* These fields define the masks and mask colors. */ 


RGB argbColor [1]; /* array of RGB colors */ 
BYTE abANDMask [1]; /* array for AND mask */ 
BYTE abXORMask [1]; /* array for XOR mask * 


The only difference between resources is the usType field. For icon resources 
this field is set to IC; for pointer resources the field is PT. 


The size of the argbColor, abANDMask, and abXORMask fields depends on 
the number of color planes and bits per pel specified by the cPlanes and 
cBitCount fields. The size of each bit mask also depends on the width and height 
of the bitmap. The bytes of the abXORMask field start immediately after the 
last byte in abANDMask. 


Icon Editor can be used to create pointers and icons. The POINTER and ICON 
statements in Resource Compiler use the pointer and icon files created by Icon 
Editor to generate pointer and icon resources. 


5.4.2 Bitmap Format 


The RT_BITMAP resource represents a bitmap. Presentation Manager applica- 
tions typically load the bitmap by using the GpiLoadBitmap function. This func- 
tion returns a handle to the bitmap. An application can use the GpiSetBitmap 
function subsequently to set the bitmap as the current bitmap of a memory 
device context. 


ergy 
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A bitmap resource has the following format: 
/* These fields are identical to the BITMAPFILEHEADER structure. */ 


USHORT usType; /* BM */ 
ULONG cbSize; /* size of resource (in bytes) */ 
USHORT xHotspot; /* x-coordinate of hot spot */ 
USHORT yHotspot; /* y-coordinate of hot spot */ 
ULONG of fBits; /* offset to abBitmap array * 


/* These fields are identical to the BITMAPINFOHEADER structure. */ 


ULONG cbFix; /* size of BITMAPINFOHEADER structure */ 
USHORT cx; /* width of bitmap (in pels) 

USHORT cy; /* height of bitmap (in pels) “4 
USHORT cPlanes; /* count of color planes in bitmaps */ 
USHORT cBitCount; /* count of bits per pel */ 


/* These fields define the bitmap and its colors. */ 


RGB argbColor([(1]; /* array of RGB colors a/ 
BYTE abBitmap [1]; /* array for bitmap bits */ 


The size of the argbColor and abBitmap fields depends on the number of color 
planes and bits per pel specified by the cPlanes and cBitCount fields. The size of 
the abBitmap field also depends on the width and height of the bitmap. 


Icon Editor can be used to create bitmaps. The BITMAP statement in Resource 
Compiler uses the bitmap files created by Icon Editor to generate bitmap 
resources. 


5.4.3 String and Message Resources 


The RT_STRING or RT_MESSAGE resource is a table of exactly 16 charac- 
ter strings representing error messages and other text used by an application. 
Presentation Manager applications typically load individual strings from a table 
by using the WinLoadString or WinLoadMessage function. These functions use 
a string identifier to determine the table containing the string and the string’s 
location in the table. 


Each string or message resource consists of a table of exactly 16 entries. Each 
entry has the following form: 


BYTE cchText; /* length of string inesud ing zero terminator a 
SZ szText[cchText]; /* zero-terminated string a/ 


String and message tables have resource identifiers starting at 1. Each string also 
has a unique identifier. A string’s identifier determines which table the string is 
in and where in the table it is located. The following C-language expressions 
specify the location of a string: 


USHORT idString; /* string ID 7 
USHORT idTable; /* resource ID of string or message table ie 
USHORT iString; /* index in table of string */ 
idTable = (idString i ao + 1; 

iString = idString % 1 


For example, if the string identifier is 1, the string is in table 1 at entry 1. If the 
string identifier is 17, the string is in table 2 at entry 1. 


The STRINGTABLE and MESSAGETABLE statements in Rasouiies Compiler 
generate string and message resources. 
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5.4.4 Menu Resource 


The RT_MENU resource represents a menu template. A menu template con- 
tains all the data needed to create a menu. A Presentation Manager application 
typically loads a menu-template resource by using the WinLoadMenu function. 


A menu-template resource has the following format: 


ULONG cbSize; /* size of menu template (in bytes) */ 
USHORT idCodePage; /* code page for menu names */ 
USHORT idClass; /* menu window-class ID */ 
USHORT cItems; 7* number of items in menu */ 


/* These fields are repeated for each item. */ 


USHORT fStyle; 7* menu-style flags */ 
USHORT fAttributes; /* menu-attribute flags */ 
USHORT cmd; /* menu-item ID */ 
SZ szItemName [1]; /* null-terminated menu name */ 


If a menu item is a submenu, its fields are followed immediately by the menu- 
template resource that defines the menu items in that submenu. 


The length of the szItemName field is variable and depends on the menu item. If 
the menu item has no name, for example, if it is a menu separator, no szItem- 
Name field is given. 


The MENU statement in Resource Compiler generates menu templates. 


5.4.5 Accelerator-Table Resource | 


The RT_ACCELTABLE resource represents a keyboard-accelerator table. 
Accelerator tables are used by Presentation Manager applications to translate 
keystrokes into commands; that is, they translate WM_CHAR messages into 
WM_COMMAND, WM_SYSCOMMAND, or WM_HELP messages. An appli- 
cation typically loads accelerator tables by using the WinLoadAccelTable func- 
tion. 


The accelerator-table resource has the following format: 
/* These fields are identical to the ACCELTABLE structure. */ 


USHORT cAccel; /* number of accelerators in the table */ 
USHORT codepage; /* code page for text * 


/* These fields are identical to the ACCEL structure. */ 


USHORT fs; /* accelerator flags */ 
USHORT key; /* keystroke to be translated & 
USHORT cmd; /* command ID of translated keystroke */ 


The fields defining the keystroke and command are repeated for each accelerator 
in the table. The fs field specifies whether the key field represents a virtual key, 
a scan code, or a key combination. 


The ACCELTABLE statement in Resource Compiler generates accelerator-table 
resources. 


5.0.1 Dialog Templates 


The RT_DIALOG resource represents a dialog-template resource. A dialog- 
template resource contains all the data needed to create a dialog window and 
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corresponding child controls. Presentation Manager applications typically use the 
WinLoadDlg or WinDlgBox function to load the resource. The function creates 
the dialog window and control windows specified by the template. 


Some applications load the resource directly by using the DosGetResource func- 
tion. Loading a dialog-template resource directly allows an application to exam- 
ine and modify the data before creating the dialog window. The application can 
then pass the data to the WinCreateDlg function to create the dialog window, or 
extract individual parameters from the data and pass the parameters to functions 
such as WinCreate Window to create other types of windows. 


A dialog-template resource has the following form: 


/* These fields are identical to 


USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
DLGTITEM 


/* These fields are identical to 


USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
ULONG 
SHORT 
SHORT 
SHORT 
SHORT 
USHORT 
USHORT 
USHORT 


The fields defining the dialog items are repeated for each window in the tem- 


cbTemplate; 
type; 
codepage; 
offadlgti; 


fsTemplateStatus; 


iItemFocus; 


coffPresParams; 


adlgti[1} 


fsIltemStatus; 
cChildren; 
cchClassName; 
offClassName; 
echText; 
offText; 
fiStyle; 

X; 


offPresParams; 


offCtlData; 


the DLGTEMPLATE structure. */ 


/* number of bytes in the template 

/* dialog type 

/* code-page for text 
* offset to lst dialog item (12) 

/* template-status flags 
* index to initial focus window 

/* offset to presentation parameters 

/* array of DLGTITEM structures 


item-status flags 


number of 
number of 
offset to 
number of 
offset to 
window 


child windows 
characters in 
class name or 
characters in 
window text 


styles 


x-coordinate of window 
y-coordinate of window 
width of window 


height of 
window ID 


window 


the DLGTITEM structure. */ 


class name 
class ID 
window text 


offset to presentation parameters 
offset to class-specific data 


plate. Data such as class name and window text appears after the fields for the 
last window. If a window has child windows, the fields of the child windows 
immediately follow the fields for the parent window. If the cchClassName field 
is zero, the offClassName field must contain a valid window-class identifier. The 
format of the class-specific data depends on the window class. In general, the 


first word of the presentation parameter data and the class-specific data must 


specify the length of that data in bytes. 


Dialog Box Editor can be used to create dialog-template resources. The 
Resource Compiler statements DLGTEMPLATE and WINDOWTEMPLATE 
generate dialog-template resources. 
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5.0.2 Dialog-Include Resource 


The RT_DLGINCLUDE resource is a filename. This resource typically is used 
in conjunction with a dialog-template resource that has the same resource 
identifier. The dialog-include resource specifies the include file that contains 
definitions for constants used in the dialog template. Although the resource is 
useful to Dialog Box Editor, other applications probably will not need it. 


The DLGINCLUDE statement in Resource Compiler generates dialog-include 
resources. 


5.0.3 Font Resource 


The RT_FONT resource represents a font resource. A font resource consists of 
the font metrics and character data that describe a font. Presentation Manager 
applications load font resources by using the GpiLoadFont function. This func- 
tion makes all font resources in a specified dynamic-link library available to the 
application. 


A font resource is identical in format to a font file. For more information, see 
the Microsoft Operating System/2 Programmer’s Reference, Volume 2. 


Font Editor can be used to create fonts. The FONT statement in Resource 
Compiler uses the font created by Font Editor to generate font resources. 


5.0.4 Font-Directory Resource 


The RT_FONTDIR resource represents a font directory. A font directory con- 
sists of the font metrics of a corresponding font resource. MS OS/2 uses font 
directories to load information about a font without having to load the entire 
font into memory. 


The font-directory resource has the following form: 


USHORT usFontDir; /* resource type (always 6) */ 
USHORT cFonts; /* count of fonts in directory a/ 
USHORT cbSize; /* size of each directory entry (in bytes) */ 


/* These fields are repeated for each font. */ 


USHORT idFont; /* resource ID for corresponding font */ 
FOCAMETRICS foca; /7* font metrics from font file a/ 


The FONTDIR statement in Resource Compiler generates a font-directory 
resource. The FONT statement of Resource Compiler also generates a font 
directory. It does this as it generates the font resource, so the FONTDIR state- 
ment is rarely used. 


5.0.5 Binary Data 


The RT_RCDATA resource represent one or more bytes of binary data. The 
binary can have any format. The application defines the content of the data. 


The RCDATA statement in Resource Compiler generates binary-data resources. 
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5. 4. 11 MS OS/2 Internal Resources 


The RT_VKEYTBL, RT_KEYTBL, RT_CHARTBL, and RT_DISPLAYINFO 
resources represent data used internally by MS OS/2. MS OS/2 uses this data to 
carry out system-level tasks—for example, translating scan codes to virtual keys 
and translating code points in a code page to font gylphs. 
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A.1 Introduction 


This chapter contains the possible error values that can be returned by the MS 
OS/2 base system functions. Before you can use these errors in your application, 
you must define the INCL_BASE, INCL_ERRORS, or INCL_DOSERRORS 
constant before including the os2.h file. The following code is a typical example: 


#define INCL_DOS 
#define INCL_DOSERRORS 


#include <os2.h> 


A.2 Errors 


The following list gives the error values that may be returned by the Dos, Kbd, 
Mou, and Vio functions. The error values are listed in numerical order, and the 
corresponding error constant is given for each value. 
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101 
102 
103 
104 
105 
106 


ERROR_INVALID_FUNCTION 
ERROR_FILE_NOT_FOUND 
ERROR_PATH_NOT_FOUND 
ERROR_TOO_MANY_OPEN.FILES 
ERROR_ACCESS_DENIED 
ERROR_INVALID_HANDLE 
ERROR_ARENA_TRASHED 
ERROR_NOT_ENOUGH_MEMORY 
ERROR_INVALID_BLOCK 
ERROR_BAD_ENVIRONMENT 
ERROR_BAD_FORMAT 
ERROR_INVALID_ACCESS 
ERROR_INVALID_DATA 


ERROR_INVALID_DRIVE 
ERROR_CURRENT_DIRECTORY 
ERROR_NOT_SAME_DEVICE 
ERROR_NO_MORE_FILES 
ERROR_WRITE_PROTECT 
ERROR_BAD_UNIT 
ERROR_NOT_READY 
ERROR_BAD_COMMAND 
ERROR_CRC 
ERROR_BAD_LENGTH 
ERROR_SEEK 
ERROR_NOT_DOS_DISK 
ERROR_SECTOR_NOT_FOUND 
ERROR_OUT_OF_PAPER 
ERROR_WRITE_FAULT 
ERROR_READ_FAULT 
ERROR_GEN_FAILURE 
ERROR_SHARING_VIOLATION 
ERROR_LOCK_VIOLATION 
ERROR_WRONG_DISK 
ERROR_FCB_UNAVAILABLE 
ERROR_SHARING_BUFFER_EXCEEDED 
ERROR_NOT_SUPPORTED 


ERROR_FILE_EXISTS 
ERROR_DUP_FCB 
ERROR_CANNOT.MAKE 
ERROR_FAIL_124 
ERROR_OUT_OF_STRUCTURES 
ERROR_ALREADY_ASSIGNED 
ERROR_INVALID_PASSWORD 
ERROR_INVALID_PARAMETER 
ERROR_NET_WRITE_FAULT 
ERROR_NO_PROC_SLOTS 
ERROR_NOT_FROZEN 
ERR_TSTOVFL 

ERR_TSTDUP 

ERROR_NO_ITEMS 
ERROR_INTERRUPT 
ERROR_TOO_MANY._SEMAPHORES 
ERROR_LEXCL_SEM_ALREADY_OWNED 
ERROR_SEM_IS_SET 
ERROR_TOO_MANY_SEM_REQUESTS 
ERROR_INVALID_AT_INTERRUPT_TIME 
ERROR_SEM_OWNER_DIED 
ERROR_SEM_USER_LIMIT 
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ERROR_DISK_CHANGE 
ERROR_DRIVE_LOCKED 
ERROR_BROKEN. PIPE 
ERROR_OPEN_FAILED 
ERROR_BUFFER_OVERFLOW 
ERROR_DISK_FULL 
ERROR_NO_MORE_SEARCH_HANDLES 
ERROR_INVALID_TARGET_HANDLE 
ERROR_PROTECTION_VIOLATION 
ERROR_VIOKBD_REQUEST 
ERROR_INVALID_CATEGORY 
ERROR_INVALID_VERIFY_SWITCH 
ERROR_BAD_DRIVER_LEVEL 
ERROR_CALL_NOT_IMPLEMENTED 
ERROR_SEM_TIMEOUT 
ERROR_INSUFFICIENT_BUFFER 
ERROR_INVALID_NAME 
ERROR_INVALID_LEVEL 
ERROR_NO_VOLUME_LABEL 
ERROR_MOD_NOT_FOUND 
ERROR_PROC_NOT_FOUND 
ERROR_WAIT_NO_CHILDREN 
ERROR_CHILD_NOT_COMPLETE 
ERROR_DIRECT_ACCESS_HANDLE 
ERROR_NEGATIVE_SEEK 
ERROR_SEEK_ON_DEVICE 
ERROR_IS_JOIN_TARGET 
ERROR_IS_JOINED 
ERROR_IS_SUBSTED 
ERROR_NOT_JOINED 
ERROR_NOT_SUBSTED 
ERROR_JOIN_TO_JOIN 
ERROR_SUBST_TO_SUBST 
ERROR_JOIN_TO_SUBST 
ERROR_SUBST_TO_JOIN 
ERROR_BUSY_DRIVE 
ERROR_SAME_DRIVE 
ERROR_DIR_NOT_ROOT 
ERROR_DIR_NOT_EMPTY 
ERROR_IS_SUBST_PATH 
ERROR_IS_JOIN_PATH 
ERROR_PATH_BUSY 
ERROR_IS_SUBST_TARGET 
ERROR_SYSTEM_TRACE 
ERROR_INVALID.EVENT_COUNT 
ERROR_TOO_MANY_MUXWAITERS 
ERROR_INVALID_LIST_ FORMAT 
ERROR_LABEL._TOO_LONG 
ERROR_TOO_MANY_TCBS 
ERROR_SIGNAL_REFUSED 
ERROR_DISCARDED 
ERROR_NOT_LOCKED 
ERROR_BAD_THREADID_ADDR 
ERROR_BAD_ARGUMENTS 
ERROR_BAD_PATHNAME 
ERROR_SIGNAL_PENDING 
ERROR_UNCERTAIN._MEDIA 
ERROR_MAX_THRDS_REACHED 
ERROR_MONITORS_NOT_SUPPORTED 
ERROR_UNC_DRIVER_NOT_INSTALLED 
ERROR_LOCK_FAILED 
ERROR_SWAPIO_FAILED 


FE SN ee Ee 


Appendix A: Error Values 411 
Pen Salsa Eu Peas ep ate cn ST ae ete tema ale ae cb eee Ti Posie enn He ts nate a 


169 ERROR_SWAPIN_FAILED 317 ERROR_MR_MID_NOT_FOUND 
170 ERROR_BUSY 318 ERROR_MR_UN_ACC_MSGF 

319 ERROR_MR_INV_MSGF_FORMAT 
180 ERROR_LINVALID_.SEGMENT_NUMBER 320 ERROR_MR_INV_IVCOUNT 
181 ERROR_LINVALID_CALLGATE 321 ERROR_MR_UN_PERFORM 
182 ERROR_INVALID_ORDINAL 322 ERROR_TS_WAKEUP 
183 ERROR_ALREADY_EXISTS 323 ERROR_TS_SEMHANDLE 
184 ERROR_NO_CHILD_PROCESS 324 ERROR_TS_NOTIMER 
185 ERROR_CHILD_ALIVE_NOWAIT 326 ERROR_TS_HANDLE 
186 ERROR_LINVALID_FLAG_NUMBER 327 ERROR_TS_DATETIME 
187 ERROR_SEM.NOT_FOUND 328 ERROR_SYS_INTERNAL 
188 ERROR_INVALID_STARTING_CODESEG 329 ERROR_QUE_CURRENT_NAME 
189 ERROR_INVALID_STACKSEG 330 ERROR_QUE_PROC_NOT_OWNED 
190 ERROR_INVALID_MODULETYPE 331 ERROR_QUE_PROC_OWNED 
191 ERROR_INVALID_EXE_SIGNATURE 332 ERROR_QUE_DUPLICATE 
192 ERROR_EXE_MARKED_LINVALID 333 ERROR_QUE_ELEMENT_NOT_EXIST 
193 ERROR_BAD_EXE_FORMAT 334 ERROR_QUE_NO_MEMORY 
194 ERROR_ITERATED_DATA_EXCEEDS_64K 335 ERROR_QUE_INVALID_NAME 
195 ERROR_LINVALID_MINALLOCSIZE 336 ERROR_QUE_INVALID_PRIORITY 
196 ERROR_DYNLINK_FROM_INVALID_RING 337 ERROR_QUE_INVALID_HANDLE 
197 ERROR_IOPL_NOT_ENABLED 338 ERROR_QUE_LINK_NOT_FOUND 
198 ERROR_LINVALID_SEGDPL 339 ERROR_QUE_MEMORY_ERROR 
199 ERROR_AUTODATASEG_EXCEEDS_64k 340 ERROR_QUE_PREV_AT_END 
200 ERROR_RING2SEG_MUST_BE_MOVABLE 341 ERROR_QUE_PROC_NO_ACCESS 
201 ERROR_RELOC_CHAIN_XEEDS_SEGLIM 342 ERROR_QUE_EMPTY 
202 ERROR_INFLOOP_IN_RELOC_CHAIN 343 ERROR_QUE.NAME_NOT_EXIST 
203 ERROR_ENVVAR_NOT_FOUND 344 ERROR_QUE_NOTLINITIALIZED 
204 ERROR_NOT_CURRENT_CTRY 345 ERROR_QUE_UNABLE_TO_ACCESS 
205 ERROR_NO_SIGNAL_SENT 346 ERROR_QUE_UNABLE_TO_ADD 
206 -ERROR_FILENAME_EXCED_RANGE 347 ERROR_QUE_UNABLE_TO_INIT 
207 ERROR_RING2_STACK_IN_USE 349 ERROR_VIO_LINVALID_.MASK 
208 ERROR_META_EXPANSION_TOO_LONG 350 ERROR_VIO_PTR 
209 ERROR_INVALID_SIGNAL_NUMBER_.. 351 ERROR_VIO_APTR 
210 ERROR_THREAD._1_INACTIVE 352 ERROR_VIO_RPTR 
211 ERROR_INFO_NOT_AVAIL 353 ERROR_VIO_CPTR 
212 ERROR_LOCKED . ; 354 ERROR_VIO_LPTR 
213 ERROR_BAD_DYNALINK 355 ERROR_VIO_MODE 
214 ERROR_TOO_MANY_MODULES 356 ERROR_VIO_WIDTH 
215 ERROR_NESTING_NOT_ALLOWED 357 ERROR_VIO_ATTR 

; 358 ERROR_VIO_ROW 
230 ERROR_BAD_PIPE : 359 ERROR_VIO_COL 
231 ERROR_PIPE_BUSY . 360 ERROR_VIO_TOPROW 
232 ERROR_NO_DATA 361 ERROR_VIO_BOTROW 
233 ERROR_PIPE_NOT_CONNECTED 362 ERROR_VIO_RIGHTCOL 
” 234 ERROR_MORE_DATA 363 ERROR_VIO_LEFTCOL 

364 ERROR_SCS_CALL 
240 ERROR_VC_DISCONNECTED 365 ERROR_SCS_VALUE 

366 ERROR_VIO_WAIT_FLAG 
303° #ERROR_INVALID_PROCID 367 ERROR_VIO_UNLOCK 
304 ERROR_INVALID_PDELTA 368 ERROR_SGS_NOT_SESSION_MGR 
305 ERROR_NOT_DESCENDANT 369 ERROR_SMG_INVALID_SGID 
306 ERROR_NOT_SESSION_MANAGER 369 ERROR_SMG_LINVALID_SESSION_ID 
307 ERROR_INVALID_PCLASS 370 ERROR_SMG_NOSG 
308 ERROR_INVALID_SCOPE 370 ERROR.SMG_NO_SESSIONS 
309 ERROR_INVALID_THREADID 371 ERROR_SMG_GRP_NOT_FOUND 
310 ERROR_DOSSUB_SHRINK 371 ERROR_SMG_SESSION_NOT_FOUND 
311 ERROR_DOSSUB_NOMEM 372 ERROR_SMG_SET_LTITLE 
312 ERROR_DOSSUB_OVERLAP 373 ERROR_KBD_PARAMETER 
313 ERROR_DOSSUB_BADSIZE 374 ERROR_KBD_NO_DEVICE 
314 ERROR_DOSSUB_BADFLAG 375 ERROR_KBD_INVALID_LIOWAIT 
315 ERROR_DOSSUB_BADSELECTOR 376 ERROR_KBD_INVALID_LENGTH 


316 ERROR_MR_MSG_TOO_LONG 377 ERROR_KBD_INVALID_ECHO_MASK 
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ERROR_KBD_INVALID_INPUT_MASK 
ERROR_MON_INVALID_PARMS 
ERROR_MON_INVALID_DEVNAME 
ERROR_MON_INVALID_HANDLE 
ERROR_MON_BUFFER_TOO_SMALL 
ERROR_MON_BUFFER_EMPTY 
ERROR_MON_DATA_TOO_LARGE 
ERROR_MOUSE_NO_DEVICE 
ERROR_MOUSE_INV_HANDLE 
ERROR_MOUSE_INV_PARMS 
ERROR_MOUSE_CANT_RESET 
ERROR_MOUSE_DISPLAY_PARMS 
ERROR_MOUSE_INV_MODULE 
ERROR_MOUSE_INV_ENTRY_PT 
ERROR_MOUSE_INV_MASK 
NO.ERROR_MOUSE_NO_DATA 
NO_ERROR_MOUSE_PTR_DRAWN 
ERROR_INVALID_FREQUENCY 
ERROR_NLS_NO_COUNTRY_FILE 
ERROR.NLS_OPEN_FAILED 
ERROR_NLS_NO_CTRY_CODE 
ERROR_NO_COUNTRY_OR_CODEPAGE 
ERROR_NLS_TABLE_TRUNCATED 
ERROR_NLS_BAD_TYPE 
ERROR_NLS_TYPE_NOT.FOUND 
ERROR_VIO_SMG_ONLY 
ERROR_VIO_INVALID_ASCIIZ 
ERROR_VIO_DEREGISTER 
ERROR_VIO_NO_POPUP 
ERROR_VIO_EXISTING_POPUP 
ERROR_KBD.SMG_ONLY 
ERROR_KBD_INVALID_ASCIIZ 
ERROR_KBD.INVALID_MASK 
ERROR_KBD_REGISTER 
ERROR_KBD.DEREGISTER 
ERROR_MOUSE_SMG_ONLY 
ERROR_MOUSE_INVALID_ASCIIZ 
ERROR_MOUSELINVALID_MASK 
ERROR_MOUSE_REGISTER 
ERROR_MOUSE_DEREGISTER 
ERROR_SMG.BAD_ACTION 
ERROR_SMG_INVALID_CALL 
ERROR_SCS_SG_NOTFOUND 
ERROR_SCS_NOT_SHELL 
ERROR_VIO_INVALID._PARMS 
ERROR_VIO_FUNCTION..OWNED 
ERROR_VIO_RETURN 
ERROR_SCS_INVALID_FUNCTION 
ERROR_SCS_NOT_SESSION_MGR 
ERROR_VIO_REGISTER 
ERROR_VIO_NO_MODE_THREAD 
ERROR_VIO_NO_SAVE_RESTORE._THD 
ERROR_VIO_IN_BG 
ERROR_VIO_ILLEGAL_DURING_POPUP 
ERROR_SMG_NOT_BASESHELL 
ERROR_SMG_BAD_STATUSREQ 
ERROR_QUE_INVALID_WAIT 
ERROR_VIO_LOCK 
ERROR._MOUSE_INVALID_IOWAIT 
ERROR_VIO_INVALID_HANDLE 
ERROR_VIO_ILLEGAL_DURING_LOCK 
ERROR_VIO_INVALID_LENGTH 


ERROR_KBD_INVALID_HANDLE 
ERROR_KBD_NO_MORE_HANDLE 
ERROR_KBD_.CANNOT_CREATE_KCB 
ERROR_KBD_CODEPAGE_LOAD_INCOMPL 
ERROR_KBD_INVALID_CODEPAGE_ID 
ERROR_KBD_NO_CODEPAGE_SUPPORT 
ERROR_KBD_FOCUS_REQUIRED 
ERROR_KBD_FOCUS_ALREADY_ACTIVE 
ERROR_KBD_KEYBOARD_BUSY 
ERROR_KBD_INVALID..CODEPAGE 
ERROR_KBD_UNABLE_TO_FOCUS 
ERROR_SMG_SESSION_NON_SELECT 
ERROR_SMG_SESSION_NOT_FOREGRND 
ERROR_SMG_SESSION_NOT_PARENT 
ERROR_SMG_INVALID._START_MODE 
ERROR_SMG_INVALID_RELATED_OPT 
ERROR_SMG_INVALID_BOND_OPTION 
ERROR_SMG_INVALID_SELECT_OPT 
ERROR_SMG_START_IN.BACKGROUND 
ERROR_SMG.INVALID_STOP_OPTION 
ERROR_SMG_BAD_RESERVE 
ERROR_SMG_PROCESS_NOT_PARENT 
ERROR_SMG_INVALID_DATA_LENGTH 
ERROR_SMG_NOT_BOUND 
ERROR_SMG_RETRY_SUB_ALLOC 
ERROR_KBD_DETACHED 
ERROR_VIO_DETACHED 
ERROR_MOU_DETACHED 
ERROR_VIO.FONT 
ERROR_VIO_USER_FONT 
ERROR_VIO_BAD_CP 
ERROR_VIO_NO_CP 

ERROR_VIO_NA_CP 
ERROR_INVALID_CODE_PAGE 
ERROR_CPLIST_TOO_SMALL 
ERROR_CP_NOT_MOVED 
ERROR_MODE_SWITCHLINIT 
ERROR_CODE_PAGE_NOT_FOUND 
ERROR_UNEXPECTED_SLOT_RETURNED 
ERROR_SMG_INVALID_TRACE_OPTION 
ERROR_VIO_INTERNAL_RESOURCE 
ERROR_VIO_SHELL_INIT 
ERROR_SMG_NO_HARD_ERRORS 
ERROR_CP_SWITCH_INCOMPLETE 
ERROR_VIO. TRANSPARENT_POPUP 
ERROR_CRITSEC_OVERFLOW 
ERROR_CRITSEC_UNDERFLOW 
ERROR_VIO_BAD_RESERVE 
ERROR_INVALID_ADDRESS 
ERROR_ZERO_SELECTORS_REQUESTED 
ERROR_NOT_ENOUGH_SELECTORS_AVA 
ERROR_INVALID_SELECTOR _ 
ERROR_SMG_INVALID_PROGRAM_TYPE 
ERROR_SMG_INVALID_PGM_CONTROL 
ERROR_SMG_INVALID_INHERIT_OPT 
ERROR_VIO_EXTENDED_SG 
ERROR_VIO_NOT_PRES_MGR_SG 
ERROR_VIO_SHIELD_OWNED 
ERROR_VIO_NO_MORE_HANDLES 
ERROR_VIO_SEE_LERROR_LOG 
ERROR_VIO_ASSOCIATED_DC 
ERROR_KBD_NO_CONSOLE 
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ERROR_MOUSE_NO_CONSOLE 
ERROR_MOUSE_INVALID_HANDLE 
ERROR_SMG_INVALID_DEBUG_PARMS 
ERROR_KBD_EXTENDED_SG 
ERROR_MOU_EXTENDED_SG 
ERROR_SMG_INVALID_ICON_FILE 


ERROR_USER_DEFINED_BASE 


ERROR_I24_WRITE.PROTECT 
ERROR_124_BAD_UNIT 
ERROR_I24_NOT_READY 
ERROR_I24_BAD_COMMAND 
ERROR_I24_CRC 

ERROR _I24_BAD_LENGTH 
ERROR_I24_SEEK 
ERROR_I24_NOT_DOS_DISK 
ERROR_I24_SECTOR_NOT_FOUND 
ERROR_124_OUT_OF_PAPER 
ERROR_I24_WRITE_FAULT 
ERROR_124_READ_FAULT 
ERROR_I24_GEN_FAILURE 
ERROR_I24_DISK_.CHANGE 
ERROR_I24_WRONG_DISK 
ERROR_I24_UNCERTAIN_MEDIA 
ERROR_124_CHAR_CALL_INTERRUPTED 
ERROR_I24_NO_MONITOR_SUPPORT 
ERROR_I24_INVALID_PARAMETER 


/* Values for error CLASS */ 


ERRCLASS_OUTRES 
ERRCLASS_TEMPSIT 
ERRCLASS_AUTH 
ERRCLASS_INTRN 
ERRCLASS_HRDFAIL 
ERRCLASS_SYSFAIL 
ERRCLASS_APPERR 
ERRCLASS._NOTFND 
ERRCLASS_BADFMT 
ERRCLASS_LOCKED 
ERRCLASS_MEDIA 
ERRCLASS_ALREADY 
ERRCLASS_UNK 
ERRCLASS_CANT 
ERRCLASS_TIME 


/* Values for error ACTION */ 


ERRACT_RETRY 
ERRACT_DLYRET 
ERRACT.USER 
ERRACT_ABORT 
ERRACT_PANIC 
ERRACT_LIGNORE 
ERRACT_INTRET 
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32768 
32769 
32770 
32771 
32772 
32773 
32774 
32775 
32776 
32777 
32778 
32779 
32780 
32781 
32782 
32783 
32784 
32785 
32786 
32787 
32788 
32789 
32790 
65026 
65027 
65028 
65033 
65034 
65037 
65039 
65040 
65043 
65045 
65047 
65048 
65049 
65074 
65077 
65078 


/* Values for error LOCUS */ 


ERRLOC_UNK 
ERRLOC_DISK 
ERRLOC_NET 
ERRLOC_SERDEV 
ERRLOC_MEM 


1° */ 

/* intercomponent error codes */ 

/* (from 8000H or 32768) */ 

/* */ 
ERROR_SWAPPER_NOT_ACTIVE 
ERROR_INVALID_SWAPID 
ERROR_IOERR_SWAP_FILE 
ERROR_SWAP_TABLE_FULL 
ERROR_SWAP_FILE_FULL 
ERROR_CANT_INIT_SWAPPER 
ERROR_SWAPPER_ALREADY_INIT 
ERROR_PMM_INSUFFICIENT._ MEMORY 
ERROR_PMM_LINVALID_FLAGS 
ERROR_PMM_INVALID_ADDRESS 
ERROR_PMM_LOCK_FAILED 
ERROR_PMM_UNLOCK_FAILED 
ERROR_PMM_MOVE_LINCOMPLETE 
ERROR_UCOM_DRIVE_RENAMED 
ERROR_UCOM_FILENAME_TRUNCATED 
ERROR_UCOM_BUFFER_LENGTH 
ERROR_MON_CHAIN_HANDLE 
ERROR_MON_NOT_REGISTERED 
ERROR_SMG_ALREADY_TOP 
ERROR_PMM_ARENA_MODIFIED 
ERROR_SMG_PRINTER_OPEN 
ERROR_PMM_SET_FLAGS_FAILED 
ERROR_INVALID_DOS_DD 
ERROR_CPSIO_CODE_PAGE_INVALID 
ERROR_CPSIO._.NO_SPOOLER 
ERROR_CPSIO_FONT_ID_INVALID 
ERROR_CPSIO_LINTERNAL_ERROR 
ERROR_CPSIO_LINVALID_PTR_NAME 
ERROR_CPSIO_NOT_ACTIVE 
ERROR_CPSIO_PID_FULL 
ERROR_CPSIO_PID_NOT_FOUND 
ERROR_CPSIO_READ_CTL_SEQ 
ERROR_CPSIO_READ_FNT_DEF 
ERROR_CPSIO_WRITE_ERROR 
ERROR_CPSIO_WRITE_FULL_ERROR 
ERROR_CPSIO_WRITE_HANDLE_BAD 
ERROR_CPSIO_SWIT_LOAD 
ERROR_CPSIO_LINV_COMMAND 
ERROR_CPSIO_NO_FONT_SWIT 
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B.1 Introduction 


This appendix lists all the escape sequences that can be used in the functions 
such as DosWrite and VioWrtTTY to control the operation of the screen while 
in text mode. The escape sequences can be used in family API, advanced video- 
input-and-output (A VIO) and full-screen programs. 


The ANSI escape sequences affect cursor positioning, erase functions, and 
screen graphics. The sequences must be typed exactly as shown with all parame- 
ters replaced with appropriate values. No spaces are allowed. The ESC in the 
syntax represents the escape character (27). 


B.2 Cursor Functions 


The following functions affect the movement of the cursor. 


B.2.1 Cursor Position 
ESC [row;colH 


or 


ESC [row;colf 


These two sequences move the cursor to the position specified by the parame- 
ters. When no parameters are provided, the cursor moves to the home position 
(the upper-left corner of the screen). 
‘B.2.2 Cursor Up 
ESC[nA 
This sequence moves the cursor up 7 rows without changing columns. If the cur- 
sor is already on the top line, MS OS/2 ignores this sequence. 
B.2.3 Cursor Down 
ESC [nB 
This sequence moves the cursor down n rows without changing columns. If the 
cursor is already on the bottom row, MS OS/2 ignores this sequence. 
B.2.4 Cursor Forward 
ESC[nC 


This sequence moves the cursor forward n columns without changing lines. If 
the cursor is already in the far-right column, MS OS/2 ignores this sequence. 
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B.2.5 Cursor Backward 
ESC[nD | 
This sequence moves the cursor back n columns without changing lines. If the 


cursor is already in the far-left column, MS OS/2 ignores this sequence. 


B.2.6 Save Cursor Position 
| ESC{[s | 


This sequence saves the current cursor position. This position can be restored 
with the Restore Cursor Position sequence. 


B.2.7 Restore Cursor Position 
ESC[u 


This sequence restores the cursor position to the Save Cursor Position value. 


B.3 Erase Functions 


The following functions erase the screen. 


B.3.1 Erase Display 
ESC[2J 


This sequence erases the screen and moves the cursor to the home position (the 
upper-left corner of the screen). 


B.3.2 Erase Line 
_ESC[K 


This sequence erases from the cursor to the end of the line (including the cursor 
position). 


B.4 Screen Graphics Functions 


The following functions affect screen graphics. 
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B.4.1 Set Graphics Rendition 


ESC[g; ... sgm 


This sequence calls the graphics functions specified by the following numeric 
values. These functions remain until the next occurrence of this sequence. This 
sequence works only if the screen device supports graphics. 


The g variable may be any of the following values: 


Value Function 

0 All attributes off 

1 Bold on 

2 Faint on 

3 Italic on 

5 Blink on 

6 Rapid-blink on 

7 Reverse video on 

8 Concealed on 

30 Black foreground 
31 Red foreground 

32 Green foreground 
33 Yellow foreground 
34 Blue foreground 
35 Magenta foreground 
36 Cyan foreground 
37 White foreground 
40 Black background 
41 Red background 
42 Green background 
43 - Yellow background 
44 Blue background 
45 Magenta background 
46 Cyan background 
47 White background 
48 Subscript 

49 Superscript 


The values 30 through 47 meet the ISO 6429 standard. 
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B.4.2 Set Mode 
ESC[=sh 


This sequence changes the screen width or type. The s variable can be one of 
the following numeric values: 


Value Function 


40 x 25 black and white 

40 x 25 color 

80 x 25 black and white 

80 x 25 color 

320 x 200 color 

320 x 200 black and white 
640 x 200 black and white 
Wraps at the end of each line 


NYA UN & WO N KF SO 


B.4.3 Reset Mode 
ESC[=sl 


The values for this escape sequence are the same as for Set Mode, except that 
the value 7 resets the mode that causes wrapping at the end of each line. 
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C.1 Introduction 
MS OS/2 supports multiple countries and languages, allowing for customization. 
This appendix lists the countries and languages supported by MS OS/2 and gives 


the related country and keyboard codes. The five supported code pages are also 
given. 


C.2 Supported Countries 


MS OS/2 supports these countries: 


Country Country code Keyboard code 
United States 001 US 
Canada (French) 002 CF 
Latin America 003 LA 
Netherlands 031 NL 
Belgium 032 BE 
France 033 FR 
Spain 034 SP 
Italy 039 IT 
Switzerland (French) 041 SF 
Switzerland (German) 041 SG 
United Kingdom 044 UK 
Denmark 045 DK 
Sweden 046 SV 
Norway 047 NO 
Germany 049 GR 
Australia 061 — 
Portugal — 351 PO 


Finland 358 SU 
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C.3 Code Pages 


A code page is a set of symbols used to display text. Each symbol represents a 
letter, digit, punctuation mark, or other character found in written languages. 
Each symbol in a code page is identified by a unique value called a code point. 
-A program displays a given symbol by supplying its corresponding code point. 


MS OS/2 provides predefined code pages. Each code page, identified by a 
unique number, contains a set of symbols for a given written language. For 
example, code page 860 contains the symbols needed to display messages in 
Portuguese. 


MS OS/2 supports the following five code pages: 
437 United States 
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Hex Digis 
: ee er tetetetotettereret pt terete 
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863 French-Canadian 


Hex Digits 
: FP EEEEEEERIEEE REE: 
2nd ng 


MER SSREACSCOWSSECSERSERNSESESED | 
Se sene ere ea eseTeERRESES 
) y 


| «| pe | a 
Pie er eo ee ee pee 


A-D 427 


EEA a SaaS a ea I a SSL a 


Index 
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ANSI escape sequences, 417-420 
ASYNC_GETBAUDRATE, 260 
ASYNC_GETCOMMERROR, 260 
ASYNC_GETCOMMEVENT, 261 
ASYNC_GETCOMMSTATUS, 262 
ASYNC_GETDCBINFO, 263 
ASYNC_GETINQUECOUNT, 264 
ASYNC_GETLINECTRL, 265 
ASYNC_GETLINESTATUS, 265 
ASYNC_GETMODEMINPUT, 266 
ASYNC_GETMODEMOUTPUT, 
266 
ASYNC_GETOUTQUECOUNT, 
267 
ASYNC_SETBAUDRATE, 268 
ASYNC_SETBREAKOFF, 268 
ASYNC_SETBREAKON, 269 
ASYNC_SETDCBINFO, 270 
ASYNC_SETLINECTRL, 270 
ASYNC_SETMODEMCTRL, 271 
ASYNC_STARTTRANSMIT, 272 
ASYNC_STOPTRANSMIT, 273 
ASYNC_TRANSMITIMM, 273 


B . 
BIOSPARAMETERBLOCK, 331 
Bit masks, 6 
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Calling conventions, 5 
C-language format, 5 
Code pages, 423-426 
CODEPAGEINFO, 332 
Constant names, 10 
COUNTRYCODE, 332 
COUNTRYINFO, 333 
CPID, 335 
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DATETIME, 336 

DCBINFO, 336 

DEFINEMUXSEMLIST, 325 

DEV_FLUSHINPUT, 274 

DEV_FLUSHOUTPUT, 275 

DEV_QUERYMONSUPPORT, 275 

DEVICEPARAMETERBLOCK, 
338 


DosAllocSeg, 18 
DosAllocShrSeg, 20 
DosBeep, 21 
DosBufReset, 21 
DosCallback, 22 
DosCallNmPipe, 23 
DosCaseMap, 24 
DosChDir, 25 
DosChgFilePtr, 26 
DosCLiAccess, 27 
DosClose, 28 
DosCloseQueue, 28 
DosCloseSem, 29 
DosConnectNmPipe, 30 
DosCreateCSAlias, 30 
DosCreateQueue, 31 
DosCreateSem, 32 
DosCreateThread, 34 
DosCwait, 35 
DosDelete, 37 
DosDevConfig, 37 
DosDevIOCtl, 39 
DosDisConnectNmPipe, 40 
DosDupHandle, 40 
DosEnterCritSec, 41 
DosErrClass, 42 
DosError, 43 
DosExecPgm, 44 
DosExit, 48 
DosExitCritSec, 49 
DosExitList, 49 
DosFSRamSemClear, 59 
DosFSRamSemRequest, 59 
DOSFSRSEM, 338 
DosFileLocks, 51 
DosFindClose, 52 
DosFindFirst, 53 
DosFindNext, 55 
DosFlagProcess, 57 
DosFreeModule, 58 
DosFreeSeg, 58 
DosGetCollate, 61 
DosGetCp, 62 
DosGetCtryInfo, 63 
DosGetDateTime, 64 
DosGetDBCSEv, 65 
DosGetEnv, 66 
DosGetHugeShift, 67 
DosGetInfoSeg, 67 
DosGetMachineMode, 69 
DosGetMessage, 70 | 


DosGetModHandle, 72 
DosGetModName, 72 
DosGetPID, 73 
DosGetPPID, 73 
DosGetProcAddr, 74 
DosGetPrty, 75 
DosGetResource, 75 
DosGetSeg, 76 
DosGetShrSeg, 77 
DosGetVersion, 77 
DosGiveSeg, 78 
DosHoldSignal, 79 
DosInsMessage, 80 
DosKillProcess, 81 
DosLoadModule, 82 
DosLockSeg, 83 _ 
DosMakeNmPipe, 84 
DosMakePipe, 85 
DosMemAvail, 86 
DosMkDir, 87 
DosMonClose, 87 
DosMonOpen, 88 
DosMonRead, 88 
DosMonReg, 89 
DosMonWrite, 90 
DosMove, 91 
DosMuxSemWait, 92 
DosNewSize, 94 
DosOpen, 95 
DosOpenQueue, 99 
DosOpenSem, 99 
DosPTrace, 105 
DosPeekNmPipe, 100 
DosPeekQueue, 101 
DosPhysicalDisk, 103 
DosPortAccess, 104 
DosPurgeQueue, 106 
DosPutMessage, 107 
DosQAppType, 107 
DosQCurDir, 108 
DosQCurDisk, 109 
DosQFHandState, 110 
DosQFileInfo, 112 
DosQFileMode, 113 
DosQFSInfo, 114 
DosQHandType, 115 
DosQNmPHandState, 116 
DosQNmPipelnfo, 117 
DosQNmPipeSemState, 118 
DosQSysInfo, 119 
DosQueryQueue, 119 
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DosQVerify, 120 
DosR2StackRealloc, 120 
DosRead, 121 
DosReadAsync, 122 
DosReadQueue, 123 
DosReallocHuge, 124 
DosReallocSeg, 125 
DosResumeThread, 126 
DosRmDir, 127 
DosScanEnv, 128 
DosSearchPath, 128 
DosSelectDisk, 130 
DosSelectSession, 131 
DosSemClear, 131 
DosSemRequest, 132 
DosSemSet, 133 
DosSemSetWait, 134 
DosSemWait, 135 
DosSendSignal, 136 
DosSetCp, 136 
DosSetDateTime, 137 _ 
DosSetFHandState, 137 
DosSetFileInfo, 139 _ 
DosSetFileMode, 140 
DosSetFSInfo, 141 
DosSetMaxFH, 141 
DosSetNmPHandState, 142 
DosSetNmPipeSem, 143 
DosSetProcCp, 143 
DosSetPrty, 144 
DosSetSession, 145 
DosSetSigHandler, 146 
DosSetVec, 149 
DosSetVerify, 150 
DosSizeSeg, 150 
DosSleep, 151 
DosStartSession, 152 
DosStopSession, 153 

- DosSubAlloc, 154 
DosSubFree, 154 
DosSubSet, 155 
DosSuspendThread, 156 
DosTimerAsync, 156 
DosTimerStart, 157 
DosTimerStop, 158 
DosTransactNmPipe, 158 
DosUnlockSeg, 159 
DosWaitNmPipe, 159 
DosWrite, 160 
DosWriteAsync, 161 
DosWriteQueue,. 163 
DSK_BLOCKREMOVABLE, 275 
DSK_FORMATVERIFY, 276 
DSK_GETDEVICEPARAMS, 277 
DSK_GETLOGICALMAP, 277 


DSK_LOCKDRIVE, 278 
DSK_READTRACK, 278 
DSK_REDETERMINEMEDIA, 
279 
DSK_SETDEVICEPARAMS, 280 
DSK_SETLOGICALMAP, 281 
DSK_UNLOCKDRIVE, 281 
DSK_VERIFYTRACK, 281 
DSK_WRITETRACK, 282 


E 
Errors, 409-413 
Escape sequences (ANSI), 417-420 


F 
FDATE, 339 
Field names, 8 
FIELDOFFSET, 325 
File formats, 375-403 
FILEFINDBUF, 339 
FILELOCK, 340 
FILESTATUS, 340 
FONTINFO, 341 
FRAME, 341 
FSALLOCATE, 341 
FSINFO, 342 
FTIME, 342 
Functions 
- directory, 15-252 
1O0Ctl, 255-317 


G 
GINFOSEG, 343 


H 

HIBYTE, 325 
HIUCHAR, 325 — 
HIUSHORT,. 325 
HOTKEY, 344 


I 
IOCtl functions, 255-317 


K 

KBD_CREATE, 283 
KBD_DESTROY, 283 
KBD_GETCODEPAGEID, 284 
KBD_GETINPUTMODE, 284 
KBD_GETINTERIMFLAG, 285 
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KBD_GETKEYBDTYPE, 285 
KBD_GETSESMGRHOTKEY, 285 
KBD_GETSHIFTSTATE, 286 
KBD_PEEKCHAR, 287 
KBD_READCHAR, 288 
KBD_SETFGNDSCREENGRP, 
288 
KBD_SETFOCUS, 289 
KBD_SETINPUTMODE, 289 
KBD_SETINTERIMFLAG, 290 
KBD_SETKCB, 290 
KBD_SETNLS, 291 
KBD_SETSESMGRHOTKEY, 291 
KBD_SETSHIFTSTATE, 292 
KBD_SETTRANSTABLE, 292 
KBD_SETTYPAMATICRATE, 
293 
KBD_XLATESCAN, 293 
KbdCharIn, 164 
KbdClose, 165 
KbdDeRegister, 166 
KbdFlushBuffer, 166 
KbdFreeFocus, 167 
KbdGetCp, 167 
KbdGetFocus, 168 
KbdGetStatus, 169 
KBDINFO, 345 
KBDKEYINFO, 346 
KbdOpen, 170 
KbdPeek, 170 
KbdRegister, 172 
KbdSetCp, 175 
KbdSetCustXt, 176 


“KbdSetFgnd, 176 


KbdSetStatus, 176 
KbdStringIn, 177 
KbdSynch, 179 
KBDTRANS, 348 
KBDTYPE, 347 
KbdXlate, 179 


L 

LINECONTROL, 349 
LINFOSEG, 350 
LOBYTE, 326 
LOUCHAR, 326 
LOUSHORT, 326 


M 

Macros, 325-329 
MAKELONG, 326 
MAKEP, 327 
MAKEPGINFOSEG, 327 
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MAKEPLINFOSEG, 327 
MAKESHORT, 328 
MAKETYPE, 328 
MAKEULONG, 328 
MAKEUSHORT, 328 
MODEMSTATUS, 351 
MONIN, 352 
MONITORPOSITION, 352 
MONOUT, 353 
MON_REGISTERMONITOR, 294 
MOU_ALLOWPTRDRAW, 295 
MOU_DRAWPTR, 295 
MOU_GETBUTTONCOUNT, 296 
MOU_GETEVENTMASK, 296 
MOU_GETHOTKEYBUTTON, 
297 
MOU_GETMICKEYCOUNT, 297 
MOU_GETMOUSTATUS, 298 
MOU_GETPTRPOS, 298 
MOU_GETPTRSHAPE, 299 
MOU_GETQUESTATUS, 300 
MOU_GETSCALEFACTORS, 300 
MOU_READEVENTQUE, 301 
MOU_REMOVEPTR, 301 
MOU_SCREENSWITCH, 302 
MOU_SETEVENTMASK, 302 
MOU_SETHOTKEYBUTTON, 303 
MOU_SETMOUSTATUS, 304 
MOU_SETPROTDRAWADDRESS, 
304 
MOUL_SETPTRPOS, 305 
MOU_SETPTRSHAPE, 306 
MOU_SETREALDRAWADDRESS, 
306 
MOU_SETSCALEFACTORS, 307 
MOU_UPDATEDISPLAYMODE, 
307 
MouClose, 181 
MouDeRegister, 181 
MouDrawPtr, 182 
MOUEVENTINFO, 353 
MouFlushQue, 182 
MouGetDevStatus, 183 
MouGetEventMask, 184 
MouGetNumButtons, 185 
MouGetNumMickeys, 185 
MouGetNumQueE]l, 186 
MouGetPtrPos, 187 
MouGetPtrShape, 187 
MouGetScaleFact, 189 
MoulnitReal, 189 
MouOpen, 190 
MOUQUEINFO, 354 
MouReadEventQue, 191 
MouRegister, 192 


MouRemovePtr, 195 
MouSetDevStatus, 196 
MouSetEventMask, 197 
MouSetPtrPos, 198 
MouSetPtrShape, 199 
MouSetScaleFact, 200 
MouSynch, 201 
MUXSEM, 354 
MUXSEMLIST, 355 


N 
Naming conventions, 7-10 
NOPTRRECT, 355 


Notational conventions, 11 


O 
OFFSETOF, 329 


Pp 
Parameter names, 8 
PDSK_GETPHYSDEVICEPARAMS, 
308 
PDSK_LOCKPHYSDRIVE, 309 
PDSK_READPHYSTRACK, 309 
PDSK_UNLOCKPHYSDRIVE, 
310 
PDSK_VERIFYPHYSTRACK, 311 
PDSK_WRITEPHYSTRACK, 311 
PIDINFO, 356 
PIPEINFO, 356 
Prefixes, 8 
PRT_ACTIVATEFONT, 312 
PRT_GETFRAMECTL, 313 
PRT_GETINFINITERETRY, 313 
PRT_GETPRINTERSTATUS, 314 
PRT_INITPRINTER, 314 
PRT_QUERYACTIVEFONT, 315 
PRT_SETFRAMECTL, 315 
PRT_SETINFINITERETRY, 316 
PRT_VERIFYFONT, 316 
PTR_GETPTRDRAWADDRESS, 
317 
PTRACEBUF, 357 
PTRDRAWFUNCTION, 359 
PTRLOC, 359 
PTRSHAPE, 360 


Q 
QUEUERESULT, 360 


R 

RATEDELAY, 361 

Resource-file formats, 
RESULTCODES, 361 
RXQUEUE, 361 


396-403 


) 

SCALEFACT, 362 
SCREENGROUP, 362 
SELECTOROF, 329 
SHIFTSTATE, 362 
STARTDATA, 363 
STATUSDATA, 365 
STRINGINBUF, 366 
Structures, 7, 331-372 


T 
TRACKFORMAT, 366 
TRACKLAYOUT, 367 
Translation tables, 375-393 
Types, 8-10, 321-324 


V 

Video fonts, 396 

Video modes, 393-396 
VioAssociate, 202 
VIOCONFIGINFO, 368 
VioCreateLogFont, 202 
VioCreatePS, 203 
VIOCURSORINFO, 369 
VioDeleteSetId, 204 
VioDeRegister, 205 
VioDestroyPS, 205 
VioEndPopUp, 205 
VIOFONTINFO, 369 
VioGetAnsi, 206 
VioGetBuf, 207 
VioGetConfig, 208 
VioGetCp, 209 
VioGetCurPos, 209 
VioGetCurType, 210 
VioGetDeviceCellSize, 211 
VioGetFont, 211 
VioGetMode, 212 
VioGetOrg, 213 
VioGetPhysBuf, 214 
VioGetState, 215 


- VIOINTENSITY, 370 


VIOMODEINFO, 370 
VioModeUndo, 216 
VioModeWait, 216 
VIOOVERSCAN, 371 
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VIOPALSTATE, 371 
VIOPHYSBUF, 372 
VioPopUp, 218 
VioPrtSc, 220 
VioPrtScToggle, 220 
VioQueryFonts, 221 
VioQuerySetIds, 222 
VioReadCellStr, 223 
VioReadCharStr, 224 
VioRegister, 225 
VioSavRedrawUndo, 229 
VioSavRedrawWait, 230 
VioScrLock, 231 
VioScrollDn, 232 
VioScrollLf, 234 
VioScrolIRt, 235 
VioScrollUp, 236 
VioScrUnLock, 237 
VioSetAnsi, 238 
VioSetCp, 239 
VioSetCurPos, 239 
VioSetCurType, 240 
VioSetDeviceCellSize, 241 
VioSetFont, 241 
VioSetMode, 242 
VioSetOrg, 243 
VioSetState, 243 
VioShowBuf, 245 
VioShowPS, 245 
VioWrtCellStr, 246 
VioWrtCharStr, 247 
VioWrtCharStrAtt, 248 
VioWrtNAttr, 249 
VioWrtNCell, 249 
VioWrtNChar, 250 
ViowrtTTY, 251 
VOLUMELABEL, 372 


Step up to 
Presentation Manager with 
the Microsoft OS/2 


Presentation Manager 


Congratulations on your purchase of the Microsofte OS/2 Programmer’s Reference Library, 
a complete guide to the features of the Microsoft OS/2 Presentation Manager. Now that 
you have the documentation, the next step is to purchase Microsoft OS/2 Presentation 
Manager Softset version 1.1, which Microsoft designed to help software developers create 
the new generation of graphically based, intuitive, easy-to-use software applications. 
Softset provides a complete, fully documented set of visual software tools to help you 
create popular applications for the graphical environment of Presentation Manager. 
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Softset Features 

¢ Dialog Editor helps you design on-screen dialog boxes. 

¢ Icon Editor helps you customize icons, cursors, and bitmap images for graphical 
applications. 

¢ Font Editor helps you create your own fonts. 


¢ Resource Compiler helps you bind resource-definition files created with the Dialog, 
Icon, and Font Editors to .EXE files. 


¢ Other Softset tools help you create and maintain libraries, create message files and 
dual-mode (DOS-OS/2) programs, and perform many other tasks. 


Combine the Softset with the Microsoft OS/2 Programmer’s Reference Library and a 
programming language such as Microsoft C Optimizing Compiler or Microsoft Macro 
Assembler with OS/2 support for a complete Presentation Manager software development 
kit. The applications you create in Presentation Manager are fully compatible with IBM« 
SAA (Systems Application Architecture). Trust the software tools from Microsoft — the 
company that developed MS. OS/2. | 


Contact your nearest local software dealer for more information. 
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dispensable to any serious OS/2 programmer. Duncan addresses a range of 
significant OS/2 issues: programming the user interface; mass storage; memory 
management; multitasking; interprocess communications; customizing filters, 
device drivers, and monitors; and using OS/2 dynamic link libraries. A valuable 
reference section includes detailed information on each of the more than 250 
system service calls in version 1.1 of the OS/2 kernel. 


800 pages, 7/s x 944, softcover, $24.95 
[Book Code 86-96106] 


PROGRAMMING THE OS/2 PRESENTATION MANAGER 

Charles Petzold | 

New! Here is the first full discussion of the features and operation of the OS/2 1.1 
Presentation Manager. If you’re developing OS/2 applications, this book will 
guide you through Presentation Manager’s system of windows, messages, and 
function calls. Petzold includes scores of valuable C programs and utilities. 


Endorsed by the Microsoft Systems Software group, this book is unparalleled for 
its clarity, detail, and comprehensiveness. Petzold covers: managing windows 
handling input and output m controlling child windows m using bitmaps, icons, 
pointers, and strings m accessing the menu and keyboard accelerators m working 
with dialog boxes m understanding dynamic linking m= and more. 

864 pages, 77/s x 94, softcover, $29.95 

[Order Code 86-96791] 


ESSENTIAL OS/2 FUNCTIONS: Programmer’s Quick Reference 
Ray Duncan 


Concise information on the essential OS/2 function calls within the application 
program interface (API). Entries are included for all kernel API functions for 
OS/2 version 1.0: Dos, Kbd, Mou, and Vio. Brief descriptions of each function 
are included, as well as a list of the required parameters, returned results, pro- 
gramming notes and warnings, family API call identification, and error codes. 
Conveniently arranged to provide quick access to the information you need. 

172 pages, 4/4 x 8, softcover, $9.95 - 

[Order Code 86-96866] 


For the Windows Programmer 


PROGRAMMING WINDOWS 
Charles Petzold 


Your fastest route to successful application programming with Windows. 

Full of indispensable reference data, tested programming advice, and page after 
page of creative sample programs and utilities. Topics include getting the most 
out of the keyboard, mouse, and timer; working with icons, cursors, bitmaps, and 
strings; exploiting Windows’ memory management; creating menus; taking 
advantage of child window controls; incorporating keyboard accelerators; using 
dynamically linkable libraries; and mastering the Graphics Device Interface 
(GDI). A thorough, up-to-date, and authoritative look at Windows’ rich arabica 
environment. 


864 pages, 7/s x 9/4 


$24.95 (sc) [Order Code 86-96049] 
$34.95 (he) [Order Code 86-96130] 


Solid Technical Information for MS-DOS® Programmers 
ADVANCED MS-DOS’ PROGRAMMING, 2nded. 


Ray Duncan a 


The preeminent source of MS-DOS information for assembly-language and 

C programmers— now completely updated with new data and programming 
advice covering: ROM BIOS for the IBM® PC, PC/AT® PS/2® and related periph- 
erals; MS-DOS through version 4.0; version 4.0 of the LIM EMS; and OS/2 
compatibility considerations. Duncan addresses key topics, including character 
devices, mass storage, memory allocation and management, and process man- 
agement. In addition, there is a healthy assortment of updated assembly-language 
and C listings that range from code fragments to complete utilities. And the ref- 
erence section, detailing each MS-DOS function and interrupt, is virtually a 
book within a book. 


512 pages, 7/s x 94, softcover, $24.95 
[Order Code 86-96668] 


THE MS-DOS* ENCYCLOPEDIA 
General Editor, Ray Duncan 


The ultimate reference for insight, data, and advice to make your MS-DOS pro- 
grams reliable, robust, and efficient. 1600 pages packed with version-specific 
data. Annotations of more than 100 system function calls, 90 user commands, 
and a host of key programming utilities. Hundreds of hands-on examples, thou- 
sands of lines of code, and handy indexes. Plus articles on debugging, writing 
filters, installable device drivers, TSRs, Windows, memory management, the fu- 
ture of MS-DOS, and much more. Researched and written by a team of MS-DOS 
experts — many involved in the creation and development of MS-DOS. Covers 
MS-DOS through version 3.2, with a special section on version 3.3. 

1600 pages, 7/4 x 10 

hardcover $134.95 [Order Code 86-96122] 

softcover $ 69.95 [Order Code 86-96833] 


Programmer’s Quick Reference Series 


MS-DOS° FUNCTIONS 

Ray Duncan 

The kind of information every seasoned programmer needs right at hand. 
Includes detailed information on MS-DOS system service calls, along with 
valuable programming notes. Covers MS-DOS through version 4. 

128 pages, 47/4 x 8, softcover, $5.95 

[Order Code 86-96411] 


IBM° ROM BIOS 
Ray Duncan 


Essential for every assembly-language or C programmer at any experience level. 
Designed for quick and easy access to information, this guide includes all the 
core information on each of the ROM BIOS services. 

128 pages, 47/4 x 8, softcover, $5.95 

{Order Code 86-96478] 


MS-DOS° EXTENSIONS 

Ray Duncan 

Brings together the hard-to-find programming information on the Lotus®/Intel®/ 
Microsoft® Expanded Memory Specification (EMS) version 4.0, the Lotus/ 
Intel/Microsoft/AST Extended Memory Specification (XMS) version 2.0, the 
Microsoft CD-ROM Extensions version 2.1, and the Microsoft Mouse driver, 
version 6. An overview of each function is accompanied by a list of its required 
parameters, returned results, and applicable programming notes. 

128 pages, 47/4 x 8, softcover, $6.95 

[Order Code 86-97229] 


Solid Language References 


MICROSOFT? C: SECRETS, SHORTCUTS & SOLUTIONS 
Kris Jamsa 


Here is a fact-filled, example-packed resource for any current or aspiring 
Microsoft C programmer working in the DOS environment. Each chapter high- 
lights specific C programming facts, tips, and traps so that key information or 


items of special interest are immediately accessible. Hundreds of short sample 
programs support Jamsa’s instruction and encourage experimentation. 

If you’re new to C, Microsoft C, or even Microsoft QuickC, Jamsa’s fast-paced, 
highly readable style will help you quickly master the fundamentals. If you’re 
a seasoned programmer, you’ll find page after page of advanced information 

_ that will hone your programming skills and make-your Microsoft C programs 
fast, clean, and efficient. Jamsa shows you how to: 

access the DOS command line m expand wildcard characters into matching 
filenames m use I/O redirection m master dynamic memory allocation m take 
advantage of C’s predefined global variables = optimize your programs for 
increased speed m enhance your program’s video appearance m make full use 
of the MAKE and LIB tools 


500 pages, 7°/s x 944, softcover, $24.95 
[Order Code 86-97112] 


PROFICIENT C 

Augie Hansen 

‘*A beautifully-conceived text, clearly written and logically organized... 

a superb guide.”’ Computer Book Review 


An information-packed handbook for intermediate to advanced DOS program- 
mers that includes dozens of file-oriented and screen-oriented C programs and 
specially developed utilities. A successful blend of programming advice and 
practical example programs. 


512 pages, 7/s x 91s, softcover, $22.95 
[Order Code 86-95710] 


VARIATIONS IN C 
_ Steve Schustack 
Foreword by Gerald Weinberg 


A superb guide for experienced programmers who want to develop efficient, 
portable, high-quality application software using C in the DOS environment. 
In addition to an overview of the basic syntax of C, Schustack provides valuable 
techniques for structured programming. A complete, 1500-line source code 
sample program illustrates key topics. Special comments and cautions are 
highlighted throughout. 


368 pages, 7/s x 9¥4, softcover, $19.95 
[Order Code 86-95249] 


STANDARD C: Programmer’s Quick Reference 
P.J. Plauger and Jim Brodie 


All the basic information needed to read and write Standard C programs that 
conform to the recently approved ANSI and ISO standard for the C program- 
ming language. Scores of diagrams illustrate the syntax rules. Whether you’ re 
new to C or familiar with an earlier dialect, this will prove ahandy companion. 


224 pages, 47/4 x 8, softcover, $7.95 
{Order Code 86-96676] 


MICROSOFT? QUICKC PROGRAMMING 
The Waite Group 


Your springboard to the core of the Microsoft QuickC. This book is loaded with 
practical information and advice on every element of QuickC, along with hun- 
dreds of specially constructed listings. Included are the tools to help you master 
QuickC’s built-in libraries; manage file input and output; work with strings, 
arrays, pointers, structures, and unions; use the graphics modes; develop and 
link large C programs; and debug your source code. 


624 pages, 7/s x 944, softcover, $19.95 
{Order Code 86-96114] 


MICROSOFT® QUICKBASIC% 2nd ed. 
Douglas Hergert 


‘‘No matter what your level of programming experience, you'll find this book 
irreplaceable when you start to program in QuickBASIC.” 


Here’s a great introduction to all the development tools, features, and user- 
interface enhancements in Microsoft QuickBASIC. And there’s more — six 
specially designed, full-length programs including a database manager, an 
information-gathering and data-analysis program, and a chart program that 
reenforce solid structured programming techniques. 


464 pages, 7°/s x 94, softcover, $19.95 
[Order Code 86-96387] 


Online Today 


THE MICROSOFT? QUICKBASIC PROGRAMMER’S TOOLBOX 
John Clark Craig | | 


This essential library of subprograms, functions, and utilities—developed to 
supercharge your QuickBASIC programs—addresses common and unusual pro- 
gramming tasks: ANSI.SYS screen control = mouse support m pop-up windows = 
graphics m string manipulations m bit manipulation m editing routines m game 
programming mg interlanguage calling m= and more. Each program takes maxi- 
mum advantage of QuickBASIC’s capabilities. You’re guaranteed to turn to this 
superb collection again and again. 


512 pages, 7°/s x 944, softcover, $22.95 
[Order Code 86-96403] 


Unbeatable Programmer’s References 


PROGRAMMER’S GUIDE TO PC & PS/2° VIDEO SYSTEMS 
Richard Wilton 


No matter what your hardware configuration, here is all the information you 
need to create fast, professional, even stunning video graphics on IBM PCs, 
compatibles, and PS/2s. No other book offers such detailed, specialized pro- 
gramming data, techniques, and advice to help you tackle the exacting 
challenges of programming directly to the video hardware. And no other book 
offers the scores of invaluable source code examples included here. Whatever 
graphic output you want —text, circles, region fill, alphanumeric character sets, 
bit blocks, animation— you’ll do it cleaner, faster, and more effectively with 
Wilton’s book. 


544 pages, 7°/s x 944, softcover, $24.95 
[Order Code 86-96163] 


THE 80386 BOOK 
Ross P. Nelson 


A clear, comprehensive, and authoritative introduction for every serious pro- 
grammer. Included are scores of superb assembly-language examples along with 
a detailed analysis of the 80386 chip. Topics covered include: the CPU, the 
memory architecture, the instructions sets of the 80386 microprocessor and the 


80387 math coprocessor, the protection scheme, the implementation of a virtual 
memory system through paging, and compatibility with earlier Intel micropro- 
cessors. Of special note is the comprehensive, clearly organized instruction set 
reference — guaranteed to be a valuable resource. 


464 pages, 7°/s x 944, softcover, $24.95 
{Order Code 86-96494] 


THE PROGRAMMER’S PC SOURCEBOOK 
Thom Hogan 


At last! A reference to save you the time required to find key pieces of technical 
data. Here is important factual information— previously published in scores of 
other sources — organized into one convenient reference. Focusing on IBM PCs 
and compatibles, PS/2s and MS-DOS, the hundreds of charts and tables cover: 
mw numeric conversions and character sets s DOS commands and utilities = 

DOS function calls and support tables s DOS BIOS calls and support tables = 
other interrupts, mouse, and EMS support = Microsoft Windows m keyboards, 
video adapters, and peripherals m chips, jumpers, switches, and registers = hard- 
ware descriptions m and more. 


560 pages, 81/2 x 11, softcover, $24.95 
[Order Code 86-96296] 


THE NEW PETER NORTON PROGRAMMER’S GUIDE 
TO THE IBM? PC & PS/2° 
Peter Norton and Richard Wilton 


A must-have classic on mastering the inner workings of IBM micros — now 
completely updated to include the PS/2 line. Sharpen your programming skills 
and learn to create simple, clean, portable programs with this successful combi- 
nation of astute programming advice, proven techniques, and solid technical 
data. Covers 8088, 80286 and 80386 microprocessors; ROM BIOS basics and 
ROM BIOS services; video, disk and keyboard basics; DOS basics, interrupts, 
and functions (through version 4); interrupts, device drivers, and video pro- 
gramming. Accept no substitutes; this is the book to have. 


528 pages, 7/s x 94, softcover, $22.95 
[Order Code 86-96635] 


The M icrosoft Press CD-ROM Library 


THE MICROSOFT? CD-ROM YEARBOOK: 1989/1990 
Microsoft Press 
Foreword by Bill Gates 


A dynamic, fact-filled portrait and analysis of the wide-ranging, fast-paced CD- 
ROM industry. Indispensable for anyone involved in the industry as well as an 
information-packed compendium for those curious about CD-ROM. Readers can 
use the book as a valuable sourcebook of facts, statistics, and forecasts, or dip 
into it for fascinating articles, reviews, and analyses of the industry. Articles 
include: 


m an absorbing history — in text and pictures — of the CD-ROM industry 

m reviews of products——hardware and software — considered outstanding or 
standard-setting 

a profiles of the leading companies and people in the industry 

m@ an overview of the process of developing a CD-ROM product 

m areview Of the legal issues of protection, rights and permissions, contracts and 
royalties surrounding CD-ROM publishing 

m the strategies and pitfalls involved in getting a CD-ROM product to market 


The breadth of accurate, up-to-date information in THE MICROSOFT 
CD-ROM YEARBOOK is impressive including: 


= comprehensive reference listings of the people, equipment, available titles, 
sources, and resources in the CD ROM industry 

m a glossary of industry terms 

m acalendar of industry events and conferences 

m specialized bibliographies 

This is the reference of fact and opinion on the industry. 


960 pages, 7°/s x 944, softcover, $79.95 
{Order Code 86-97203] 


CD ROM: THE NEW PAPYRUS 
Edited by Steve Lambert and Suzanne Ropiequet 


‘*This 619-page compendium, with contributions from more than 30 optical- 
memory specialists, promises to become the bible of CD ROM.”’ David Bunnell, 
Macworld 


This special compendium of 45 articles by leading authorities examines every 
facet of compact disc read only memory technology: hardware, software, 
applications, publishing systems, marketing, and the user interface. Includes 
introductory as well as technical information. 


608 pages, 77/s x 944, softcover, $21.95 
[Order Code 86-95454] 


CD ROM 2: OPTICAL PUBLISHING 
Edited by Suzanne Ropiequet with John Einberger and Bill Zoellick 
‘Recommended reading for any information professional.’’ Online Today 


This is a comprehensive overview of the entire optical publishing process. 
Topics include: evaluating and defining storage and retrieval methods; collect- 
ing, preparing, and indexing data; updating strategies; data protection and 
copyrighting; and more. Plus information on the High Sierra Logical Format. In 
addition, the editors trace the development of two CD ROM projects from initial 
concept to final product. For publishers, technical managers, and entrepreneurs. 


384 pages, 7/s x 944, softcover, $22.95 
[Order Code 86-95686] 


INTERACTIVE MULTIMEDIA 
Foreword by John Sculley 
Edited by Sueanne Ambron and Kristina Hooper 


Apple Computer Corp. brought together leading researchers and developers to 
produce this informative collection of 21 articles. The result is a sourcebook of 
ideas and inspiration for software and hardware developers, educators, pub- 
lishers, and information providers. The contributors, including Doug Englebart, 
Sam Gibbon, and Peter Cook, represent the industries — computers, television, 
and publishing — whose products will provide the content and media for educa- 
tion in the future. Filled with examples and pilot projects that define the new 
meaning of multimedia. Published with Apple Computer, Inc. 


352 pages, 7/s x 94, softcover, $24.95 
[Order Code 86-96379] 


Also of Note 


COMPUTER LIB/DREAM MACHINES 
Ted Nelson 


**An exuberant, multifont compendium of computing proverbs, anecdotes, jokes, 
predictions, and politics. Still as fresh and relevant as it was a dozen years ago, 
Computer Lib is a browser’ s gold mine.’’ PC World 


Published in 1974, Ted Nelson’s COMPUTER LIB was an original, off-the-wall 
compendium of Nelson’s visionary wisdom on the state of computing. Immedi- 

- ately embraced by hackers, COMPUTER LIB/DREAM MACHINES provided 
inspiration to today’s industry greats. Nelson anticipated the personal computer 
revolution, made outlandish predictions (many of which have proven true), and 
expounded on his vision of non-sequential data storage — something he dubbed 
hypertext. Long unavailable, COMPUTER LIB has been updated with new 
commentaries and insights from Nelson. 


336 pages, 9/4 x 95/4, softcover, $18.95 
{Order Code 86-96031] 


Microsoft Press books are available wherever books and software are sold. 
Or you can place a credit card order by calling 1-800-638-3030 (8 AM to 4:30 PM EST). 
In Maryland, call collect: 824-7300. 


U.S.A. 
U.K. 


Austral. 


(recommended) 
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-OS/2 "a" 


The Microsoft’ Operating System/2 Programmer’s Reference Library should 

be the cornerstone of every OS/2 developer’s programming library. These vol- 
umes are required references for professional developers creating applications 
for the retail market; for corporate programmers creating in-house software pro- 
grams; for hardware manufacturers creating software to support their products; 
and for all other experienced programmers working in the OS/2 environment. 


Each volume in the series is written by a team of OS/2 specialists — many 
involved in the development and ongoing enhancement of OS/2 at Microsoft. 
These books provide in-depth, accurate, and up-to-date information from the 
Microsoft OS/2 Presentation Manager Toolkit — the software development kit 
essential for creating OS/2 applications. 


Volume 1 


Volume | details the conceptual framework of the MS* OS/2 Application Pro- 
gramming Interface (API). Included are thorough descriptions of MS* OS/2 
programming models, overviews of basic programming considerations, and 
explanations of the interaction between the API and the rest of the MS° OS/2 
system. Sections include Introducing MS* OS/2, Window Manager, Graphics 
Programming Interface, and System Services. 


Volume 2 


Volume 2 is a comprehensive, alphabetic listing of MS’ OS/2 Presentation 
Manager functions as well as the structures and file formats used with these 
functions. Each function entry includes information on syntax; descriptions of 
the function’s actions and purpose; parameters and field definitions; return 
values, error values, and restrictions; source-code examples; and programming 
notes. Appendix included. 


Volume 3 


Similar in format to Volume 2, Volume 3 is a comprehensive alphabetic listing 
of MS* OS/2 base functions, including their structures and file formats. 
Appendixes included. 


$19.95 
£18.95 
$29.95 


